+3

.github/ISSUE_TEMPLATE/bug_report.md

··· 7 7 assignees: '' 8 8 9 9 --- 10 10 + Please read https://den.oeiuwq.com/tutorials/bogus/ first. 10 11 11 12 If you have found a bug, please share a reproduction repository with us. 12 13 ··· 20 21 ``` 21 22 22 23 Your repository will help us verify that we can reproduce the bug in a minimal environment - Your repo has CI actions enabled. When the bug has been fixed we can use your same code as a non-regression test to ensure bugs do not appear again. 24 24 + 25 25 + If you found a bug regression please edit the CI workflow to include main and any other revision to test and show something was working before main. 23 26 24 27 ### Description 25 28

+1 -1

README.md

··· 27 27 - [Dendritic](https://den.oeiuwq.com/explanation/core-principles/): **same** concern, **different** Nix classes. 28 28 - [Flake optional](https://den.oeiuwq.com/guides/no-flakes/). Stable/unstable Nix, with/without flake-parts. 29 29 - [DRY](modules/aspects/provides/unfree/unfree.nix) & [`class`-generic](modules/aspects/provides/primary-user.nix) — [parametric](https://den.oeiuwq.com/explanation/parametric/) over `host`/`home`/`user`. 30 30 - - Context-aware [dependencies](https://den.oeiuwq.com/explanation/context-system/); `host<->user` [bidirectional](https://den.oeiuwq.com/guides/bidirectional/) contributions. 30 30 + - Context-aware [dependencies](https://den.oeiuwq.com/explanation/context-system/); `host<->user` [bidirectional](https://den.oeiuwq.com/guides/configure-aspects/) contributions. 31 31 - [Share](https://den.oeiuwq.com/guides/namespaces/) aspects across repos. [Routable](templates/example/modules/aspects/eg/routes.nix) configs. 32 32 - Custom [factories](https://github.com/vic/den/blob/f5c44098e4855e07bf5cbcec00509e75ddde4220/templates/ci/modules/homes.nix#L20) for any Nix `class`. Per-host `stable`/`unstable` channels. 33 33 - Freeform [schemas](https://den.oeiuwq.com/reference/schema/) (no `specialArgs`) with [base](https://github.com/vic/den/pull/119) modules.

+13 -10

docs/astro.config.mjs

··· 45 45 ], 46 46 }, 47 47 { 48 48 - label: 'Adopt', 48 48 + label: 'Templates', 49 49 items: [ 50 50 - { label: 'Getting Started', slug: 'tutorials/getting-started' }, 51 51 - { label: 'Your First Aspect', slug: 'tutorials/first-aspect' }, 52 52 - { label: 'Context-Aware Configs', slug: 'tutorials/context-aware' }, 50 50 + { label: 'Overview', slug: 'tutorials/overview' }, 51 51 + { label: 'Minimal', slug: 'tutorials/minimal' }, 52 52 + { label: 'Default', slug: 'tutorials/default' }, 53 53 + { label: 'Example', slug: 'tutorials/example' }, 54 54 + { label: 'No-Flake', slug: 'tutorials/noflake' }, 55 55 + { label: 'Bug Reproduction', slug: 'tutorials/bogus' }, 56 56 + { label: 'CI Tests', slug: 'tutorials/ci' }, 53 57 ], 54 58 }, 55 59 { 56 56 - label: 'How-To Guides', 60 60 + label: 'Cookbook', 57 61 items: [ 58 62 { label: 'Declare Hosts & Users', slug: 'guides/declare-hosts' }, 59 59 - { label: 'Bidirectional Dependencies', slug: 'guides/bidirectional' }, 63 63 + { label: 'Configure Aspects', slug: 'guides/configure-aspects' }, 60 64 { label: 'Home-Manager Integration', slug: 'guides/home-manager' }, 61 65 { label: 'Use Batteries', slug: 'guides/batteries' }, 62 66 { label: 'Share with Namespaces', slug: 'guides/namespaces' }, 63 67 { label: 'Angle Brackets Syntax', slug: 'guides/angle-brackets' }, 64 68 { label: 'Custom Nix Classes', slug: 'guides/custom-classes' }, 65 65 - { label: 'Use Without Flakes', slug: 'guides/no-flakes' }, 66 69 { label: 'Migrate to Den', slug: 'guides/migrate' }, 67 70 { label: 'Debug Configurations', slug: 'guides/debug' }, 68 71 ], ··· 73 76 { label: 'den.ctx', slug: 'reference/ctx' }, 74 77 { label: 'den.lib', slug: 'reference/lib' }, 75 78 { label: 'den.aspects', slug: 'reference/aspects' }, 76 76 - { label: 'Entity Schema', slug: 'reference/schema' }, 77 77 - { label: 'Batteries', slug: 'reference/batteries' }, 78 78 - { label: 'Configuration Output', slug: 'reference/output' }, 79 79 + { label: 'den.base', slug: 'reference/schema' }, 80 80 + { label: 'den.provides', slug: 'reference/batteries' }, 81 81 + { label: 'flake.*', slug: 'reference/output' }, 79 82 ], 80 83 }, 81 84 ],

+5 -1

docs/src/content/docs/explanation/aspects.md docs/src/content/docs/explanation/aspects.mdx

··· 3 3 description: How aspects use the __functor pattern for context-awareness. 4 4 --- 5 5 6 6 + import { Aside } from '@astrojs/starlight/components'; 7 7 + 6 8 7 7 - > Use the source, Luke: [`nix/lib.nix`](https://github.com/vic/den/blob/main/nix/lib.nix) · Built on [flake-aspects](https://github.com/vic/flake-aspects) 9 9 + <Aside title="Use the Source, Luke" icon="github"> 10 10 + [`nix/lib.nix`](https://github.com/vic/den/blob/main/nix/lib.nix) · Built on [flake-aspects](https://github.com/vic/flake-aspects) 11 11 + </Aside> 8 12 9 13 ## The __functor Pattern 10 14

-188

docs/src/content/docs/explanation/context-pipeline.md

··· 1 1 - --- 2 2 - title: OS Context Pipeline 3 3 - description: The complete data flow from host declaration to final configuration. 4 4 - --- 5 5 - 6 6 - > Use the source, Luke: [`modules/context/types.nix`](https://github.com/vic/den/blob/main/modules/context/types.nix) · [`modules/context/os.nix`](https://github.com/vic/den/blob/main/modules/context/os.nix) · HM: [`hm-os.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/hm-os.nix) · [`hm-integration.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/hm-integration.nix) 7 7 - 8 8 - ## The NixOS/nix-Darwin Pipeline 9 9 - 10 10 - When Den evaluates a host configuration, data flows through a pipeline 11 11 - of context transformations. Here is the complete picture: 12 12 - 13 13 - ```mermaid 14 14 - graph TD 15 15 - Host["den.hosts.x86_64-linux.igloo"] 16 16 - Host -->|"initial context"| CtxHost["ctx.host { host }"] 17 17 - 18 18 - CtxHost -->|"conf"| HA["den.aspects.igloo<br/>(fixedTo { host })"] 19 19 - CtxHost -->|"into.default"| CtxDef1["<b>ctx.default</b> { host }"] 20 20 - CtxHost -->|"into.user<br/>(per user)"| CtxUser["ctx.user { host, user }"] 21 21 - CtxHost -->|"into.hm-host<br/>(if HM detected)"| CtxHM["ctx.hm-host { host }"] 22 22 - 23 23 - CtxUser -->|"conf"| UA["den.aspects.tux<br/>(fixedTo { host, user })"] 24 24 - CtxUser -->|"into.default"| CtxDef2["<b>ctx.default</b> { host, user }"] 25 25 - 26 26 - CtxHM -->|"conf"| HMmod["Import HM module"] 27 27 - CtxHM -->|"into.hm-user<br/>(per HM user)"| CtxHMU["ctx.hm-user { host, user }"] 28 28 - 29 29 - CtxHMU -->|"forward homeManager<br/>into host"| FW["home-manager.users.tux"] 30 30 - 31 31 - CtxDef1 -->|"includes"| DI1["<b>den.default.{class}</b> ()<br/>den.default.includes<br/>(host-context funcs)"] 32 32 - CtxDef2 -->|"includes"| DI2["den.default.includes<br/>(user-context funcs)"] 33 33 - ``` 34 34 - 35 35 - ## Stage by Stage 36 36 - 37 37 - ### 1. Host Entry 38 38 - 39 39 - Den reads `den.hosts.x86_64-linux.igloo` and applies the initial context `den.ctx.host`: 40 40 - 41 41 - ```nix 42 42 - den.ctx.host { host = den.hosts.x86_64-linux.igloo; } 43 43 - ``` 44 44 - 45 45 - ### 2. Host Aspect Resolution 46 46 - 47 47 - `den.ctx.host.conf` locates `den.aspects.igloo` and fixes it to the host context. 48 48 - All owned configs and static includes from the host aspect are collected. 49 49 - 50 50 - ### 3. Default configs (host-level) 51 51 - 52 52 - `den.ctx.host.into.default` produces `{ host }` for `den.ctx.default`, which 53 53 - activates `den.default.includes` functions matching `{ host, ... }`. 54 54 - 55 55 - ### 4. User Enumeration 56 56 - 57 57 - `den.ctx.host.into.user` maps over `host.users`, producing one 58 58 - `den.ctx.user { host, user }` per user. 59 59 - 60 60 - ### 5. User Aspect Resolution 61 61 - 62 62 - `den.ctx.user.conf` locates both the user's aspect (`den.aspects.tux`) and the 63 63 - host's aspect, collecting contributions from both directions. 64 64 - 65 65 - ### 6. Default configs (user-level) 66 66 - 67 67 - `ctx.user.into.default` activates `den.default.includes` again, this time 68 68 - with `{ host, user }` — functions needing user context now match. 69 69 - 70 70 - ### 7. Home-Manager Detection 71 71 - 72 72 - `den.ctx.host.into.hm-host` checks if the host has users with `homeManager` 73 73 - class and a supported OS. If so, it activates `den.ctx.hm-host`. 74 74 - 75 75 - ### 8. HM Module Import (host-level) 76 76 - 77 77 - `den.ctx.hm-host.conf` imports the Home-Manager NixOS/Darwin module. 78 78 - 79 79 - ### 9. HM User config collection (user-level) 80 80 - 81 81 - For each HM user, `ctx.hm-user` uses `den._.forward` to take 82 82 - `homeManager` class configs and insert them into 83 83 - `home-manager.users.<name>` on the host. 84 84 - 85 85 - ## Home-Manager Detection Criteria 86 86 - 87 87 - `ctx.host.into.hm-host` does not always activate. It checks three conditions 88 88 - (see [`hm-os.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/hm-os.nix)): 89 89 - 90 90 - 1. **OS class is supported** — the host's class is `nixos` or `darwin` 91 91 - 2. **HM users exist** — at least one user has `class = "homeManager"` 92 92 - 3. **HM module available** — `inputs.home-manager` exists, or the host has a custom `hm-module` 93 93 - 94 94 - All three must be true. Hosts without users, or with only non-HM users, 95 95 - skip the entire HM pipeline. 96 96 - 97 97 - ## Duplication Caveat with den.default 98 98 - 99 99 - `den.default` (alias for `den.ctx.default`) is included at **{host}**, **{host, user}**, **{home}** 100 100 - context stages — once for the host context and once __per each__ user. 101 101 - 102 102 - This means: 103 103 - 104 104 - - **Owned** configs and **static** includes from `den.default` can appear 105 105 - multiple times in the final configuration 106 106 - - For `mkMerge`-compatible options (most NixOS options), this is harmless 107 107 - - For options of **types.listOf** or **types.package**, you may get duplicate entries. 108 108 - 109 109 - To avoid duplication, use `den.lib.take.exactly` to restrict which 110 110 - context stages a function matches: 111 111 - 112 112 - ```nix 113 113 - den.default.includes = [ 114 114 - (den.lib.take.exactly ({ host }: { nixos.x = 1; })) 115 115 - ]; 116 116 - ``` 117 117 - 118 118 - This function runs only in the `{ host }` context, not in `{ host, user }`. 119 119 - 120 120 - :::tip 121 121 - Prefer attaching configurations directly to specific host or user aspects, or use 122 122 - `den.ctx.host` / `den.ctx.user` includes, rather than overloading `den.default` 123 123 - for everything. 124 124 - ::: 125 125 - 126 126 - ## Standalone Home-Manager 127 127 - 128 128 - For `den.ctx.home`, the pipeline is shorter: 129 129 - 130 130 - ```mermaid 131 131 - graph TD 132 132 - Home["den.homes.x86_64-linux.tux"] 133 133 - Home -->|"creates"| CtxHome["ctx.home { home }"] 134 134 - CtxHome -->|"conf"| HomeA["den.aspects.tux<br/>(fixedTo { home })"] 135 135 - CtxHome -->|"into.default"| CtxDef["ctx.default { home }"] 136 136 - ``` 137 137 - 138 138 - ## den.default Is an Alias 139 139 - 140 140 - `den.default` is an alias for `den.ctx.default`. When you write: 141 141 - 142 142 - ```nix 143 143 - den.default.homeManager.home.stateVersion = "25.11"; 144 144 - den.default.includes = [ den._.define-user ]; 145 145 - ``` 146 146 - 147 147 - You are actually setting `den.ctx.default.homeManager...` and 148 148 - `den.ctx.default.includes`. This means `den.default` is a full 149 149 - context type — it has `conf`, `into`, `includes`, and owned attributes. 150 150 - 151 151 - ### How den.default Receives Data 152 152 - 153 153 - `host`, `user`, and `home` aspects **do not** include `den.default` directly. 154 154 - Instead, each context type transforms **into** `default`: 155 155 - 156 156 - ```nix 157 157 - den.ctx.host.into.default = lib.singleton; # passes { host } 158 158 - den.ctx.user.into.default = lib.singleton; # passes { host, user } 159 159 - den.ctx.home.into.default = lib.singleton; # passes { home } 160 160 - ``` 161 161 - 162 162 - This means `den.default` is reached through the declarative context 163 163 - pipeline, not by direct inclusion. The data flowing into `den.default` 164 164 - is whatever the source context provides. 165 165 - 166 166 - ### Best Practices 167 167 - 168 168 - `den.default` is useful for global settings like `home.stateVersion`. 169 169 - However, prefer attaching parametric includes to the appropriate 170 170 - context type instead: 171 171 - 172 172 - | Instead of | Use | 173 173 - |-----------|-----| 174 174 - | `den.default.includes = [ hostFunc ]` | `den.ctx.host.includes = [ hostFunc ]` | 175 175 - | `den.default.includes = [ hmFunc ]` | `den.ctx.hm-host.includes = [ hmFunc ]` | 176 176 - | `den.default.nixos.x = 1` | `den.ctx.host.nixos.x = 1` | 177 177 - 178 178 - ## Why This Design? 179 179 - 180 180 - Each context type is **independent** and **composable**. You can: 181 181 - 182 182 - - Add new context types without modifying existing ones 183 183 - - Attach aspects to any stage of the pipeline 184 184 - - Create custom transformations for domain-specific needs 185 185 - - Override any built-in context behavior 186 186 - 187 187 - The pipeline is not hardcoded — it's declared through `den.ctx` definitions 188 188 - that you can inspect, extend, and customize.

+208

docs/src/content/docs/explanation/context-pipeline.mdx

··· 1 1 + --- 2 2 + title: OS Context Pipeline 3 3 + description: The complete data flow from host declaration to final configuration. 4 4 + --- 5 5 + 6 6 + 7 7 + import { Aside } from '@astrojs/starlight/components'; 8 8 + 9 9 + <Aside title="Use the Source, Luke" icon="github"> 10 10 + [`modules/context/types.nix`](https://github.com/vic/den/blob/main/modules/context/types.nix) · [`modules/context/os.nix`](https://github.com/vic/den/blob/main/modules/context/os.nix) · HM: [`hm-os.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/hm-os.nix) · [`hm-integration.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/hm-integration.nix) 11 11 + </Aside> 12 12 + 13 13 + ## The NixOS/nix-Darwin Pipeline 14 14 + 15 15 + When Den evaluates a host configuration, data flows through a pipeline 16 16 + of context transformations. Here is the complete picture: 17 17 + 18 18 + ```mermaid 19 19 + graph TD 20 20 + Host["den.hosts.x86_64-linux.igloo"] 21 21 + Host -->|"initial context"| CtxHost["ctx.host { host }"] 22 22 + 23 23 + CtxHost -->|"_.host"| HA["den.aspects.igloo<br/>(fixedTo { host })"] 24 24 + CtxHost -->|"into.default"| CtxDef1["<b>ctx.default</b> { host }"] 25 25 + CtxHost -->|"into.user<br/>(per user)"| CtxUser["ctx.user { host, user }"] 26 26 + CtxHost -->|"into.hm-host<br/>(if HM detected)"| CtxHM["ctx.hm-host { host }"] 27 27 + 28 28 + CtxUser -->|"_.user (self)"| UA["den.aspects.tux<br/>(fixedTo { host, user })"] 29 29 + CtxHost -->|"_.user (cross)"| XP["host aspect includes<br/>matching { host, user }"] 30 30 + CtxUser -->|"into.default"| CtxDef2["<b>ctx.default</b> { host, user }"] 31 31 + 32 32 + CtxHM -->|"_.hm-host"| HMmod["Import HM module"] 33 33 + CtxHM -->|"into.hm-user<br/>(per HM user)"| CtxHMU["ctx.hm-user { host, user }"] 34 34 + 35 35 + CtxHMU -->|"forward homeManager<br/>into host"| FW["home-manager.users.tux"] 36 36 + 37 37 + CtxDef1 -->|"includes"| DI1["<b>den.default.{class}</b> ()<br/>den.default.includes<br/>(host-context funcs)"] 38 38 + CtxDef2 -->|"includes"| DI2["den.default.includes<br/>(user-context funcs)"] 39 39 + ``` 40 40 + 41 41 + ## Stage by Stage 42 42 + 43 43 + ### 1. Host Entry 44 44 + 45 45 + Den reads `den.hosts.x86_64-linux.igloo` and applies the initial context `den.ctx.host`: 46 46 + 47 47 + ```nix 48 48 + den.ctx.host { host = den.hosts.x86_64-linux.igloo; } 49 49 + ``` 50 50 + 51 51 + ### 2. Host Aspect Resolution 52 52 + 53 53 + `den.ctx.host.provides.host` (aliased as `_.host`) locates `den.aspects.igloo` 54 54 + and fixes it to the host context. All owned configs and static includes from the 55 55 + host aspect are collected. 56 56 + 57 57 + ### 3. Default configs (host-level) 58 58 + 59 59 + `den.ctx.host.into.default` produces `{ host }` for `den.ctx.default`, which 60 60 + activates `den.default.includes` functions matching `{ host, ... }`. 61 61 + 62 62 + ### 4. User Enumeration 63 63 + 64 64 + `den.ctx.host.into.user` maps over `host.users`, producing one 65 65 + `den.ctx.user { host, user }` per user. 66 66 + 67 67 + ### 5. User Aspect Resolution 68 68 + 69 69 + Two providers contribute to user context: 70 70 + - `den.ctx.user.provides.user` (self-provider) — locates the user's own aspect (`den.aspects.tux`) 71 71 + - `den.ctx.host.provides.user` (cross-provider) — the host's contribution, dispatching host aspect includes matching `{ host, user }` 72 72 + 73 73 + ### 6. Default configs (user-level) 74 74 + 75 75 + `ctx.user.into.default` activates `den.default.includes` again, this time 76 76 + with `{ host, user }` — functions needing user context now match. 77 77 + Because `den.ctx.default` was already visited in stage 3, only parametric 78 78 + includes are dispatched (owned and static configs are **deduplicated**). 79 79 + 80 80 + ### 7. Home-Manager Detection 81 81 + 82 82 + `den.ctx.host.into.hm-host` checks if the host has users with `homeManager` 83 83 + class and a supported OS. If so, it activates `den.ctx.hm-host`. 84 84 + 85 85 + ### 8. HM Module Import (host-level) 86 86 + 87 87 + `den.ctx.hm-host.provides.hm-host` imports the Home-Manager NixOS/Darwin module. 88 88 + 89 89 + ### 9. HM User config collection (user-level) 90 90 + 91 91 + For each HM user, `ctx.hm-user` uses `den._.forward` to take 92 92 + `homeManager` class configs and insert them into 93 93 + `home-manager.users.<name>` on the host. 94 94 + 95 95 + ## Home-Manager Detection Criteria 96 96 + 97 97 + `ctx.host.into.hm-host` does not always activate. It checks three conditions 98 98 + (see [`hm-os.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/hm-os.nix)): 99 99 + 100 100 + 1. **OS class is supported** — the host's class is `nixos` or `darwin` 101 101 + 2. **HM users exist** — at least one user has `class = "homeManager"` 102 102 + 3. **HM module available** — `inputs.home-manager` exists, or the host has a custom `hm-module` 103 103 + 104 104 + All three must be true. Hosts without users, or with only non-HM users, skip the entire HM pipeline. 105 105 + 106 106 + ## Automatic Deduplication 107 107 + 108 108 + `den.default` (alias for `den.ctx.default`) is reached at **`{host}`**, **`{host, user}`**, 109 109 + and **`{home}`** context stages — once for the host context and once per user. 110 110 + 111 111 + Den's `ctxApply` automatically deduplicates includes using a seen-set: 112 112 + 113 113 + - **First visit** to a context type: includes **owned + static + parametric** configs via `fixedTo` 114 114 + - **Subsequent visits**: includes only **parametric** configs via `atLeast` 115 115 + 116 116 + Additionally, for each context, two providers are called: 117 117 + - **Self-provider** (`provides.${name}`) — the target's own aspect lookup 118 118 + - **Cross-provider** (`source.provides.${target}`) — the source's contribution (if defined) 119 119 + 120 120 + ```mermaid 121 121 + graph TD 122 122 + H["ctx.host { host }"] -->|"into.default (1st visit)"| D1["ctx.default { host }<br/><b>fixedTo</b>: owned + statics + parametric<br/>+ self-provider + cross-provider"] 123 123 + H -->|"into.user"| U["ctx.user { host, user }"] 124 124 + U -->|"into.default (2nd visit)"| D2["ctx.default { host, user }<br/><b>atLeast</b>: parametric only<br/>+ self-provider + cross-provider"] 125 125 + ``` 126 126 + 127 127 + This means: 128 128 + 129 129 + - **Owned** configs and **static** includes from `den.default` appear **exactly once** 130 130 + - **Parametric** functions in `den.default.includes` still run at every stage 131 131 + (each may match different context shapes) 132 132 + - Options of `types.package` or `types.listOf` no longer get duplicate entries 133 133 + 134 134 + <Aside> 135 135 + For parametric includes in `den.default.includes`, use `den.lib.take.exactly` 136 136 + to restrict which context stages a function matches: 137 137 + 138 138 + ```nix 139 139 + den.default.includes = [ den.aspects.foo ]; 140 140 + den.aspects.foo = take.exactly ({ host }: { nixos.x = 1; }); 141 141 + ``` 142 142 + 143 143 + This function runs only with `{ host }` context, not with `{ host, user }`. 144 144 + </Aside> 145 145 + 146 146 + ## Standalone Home-Manager 147 147 + 148 148 + For `den.ctx.home`, the pipeline is shorter: 149 149 + 150 150 + ```mermaid 151 151 + graph TD 152 152 + Home["den.homes.x86_64-linux.tux"] 153 153 + Home -->|"creates"| CtxHome["ctx.home { home }"] 154 154 + CtxHome -->|"_.home"| HomeA["den.aspects.tux<br/>(fixedTo { home })"] 155 155 + CtxHome -->|"into.default"| CtxDef["ctx.default { home }"] 156 156 + ``` 157 157 + 158 158 + ## den.default Is an Alias 159 159 + 160 160 + `den.default` is an alias for `den.ctx.default`. When you write: 161 161 + 162 162 + ```nix 163 163 + den.default.homeManager.home.stateVersion = "25.11"; 164 164 + den.default.includes = [ den._.define-user ]; 165 165 + ``` 166 166 + 167 167 + You are actually setting `den.ctx.default.homeManager...` and 168 168 + `den.ctx.default.includes`. This means `den.default` is a full 169 169 + context type — it has self-named providers, `into`, `includes`, and owned attributes. 170 170 + 171 171 + ### How den.default Receives Data 172 172 + 173 173 + `host`, `user`, and `home` aspects **do not** include `den.default` directly. 174 174 + Instead, each context type transforms **into** `default`: 175 175 + 176 176 + ```nix 177 177 + den.ctx.host.into.default = lib.singleton; # passes { host } 178 178 + den.ctx.user.into.default = lib.singleton; # passes { host, user } 179 179 + den.ctx.home.into.default = lib.singleton; # passes { home } 180 180 + ``` 181 181 + 182 182 + This means `den.default` is reached through the declarative context 183 183 + pipeline, not by direct inclusion. The data flowing into `den.default` 184 184 + is whatever the source context provides. 185 185 + 186 186 + ### Best Practices 187 187 + 188 188 + `den.default` is useful for global settings like `home.stateVersion`. 189 189 + However, prefer attaching parametric includes to the appropriate 190 190 + context type instead: 191 191 + 192 192 + | Instead of | Use | 193 193 + |-----------|-----| 194 194 + | `den.default.includes = [ hostFunc ]` | `den.ctx.host.includes = [ hostFunc ]` | 195 195 + | `den.default.includes = [ hmFunc ]` | `den.ctx.hm-host.includes = [ hmFunc ]` | 196 196 + | `den.default.nixos.x = 1` | `den.ctx.host.nixos.x = 1` | 197 197 + 198 198 + ## Why This Design? 199 199 + 200 200 + Each context type is **independent** and **composable**. You can: 201 201 + 202 202 + - Add new context types without modifying existing ones 203 203 + - Attach aspects to any stage of the pipeline 204 204 + - Create custom transformations for domain-specific needs 205 205 + - Override any built-in context behavior 206 206 + 207 207 + The pipeline is not hardcoded — it's declared through `den.ctx` definitions 208 208 + that you can inspect, extend, and customize.

+42 -22

docs/src/content/docs/explanation/context-system.md docs/src/content/docs/explanation/context-system.mdx

··· 3 3 description: How den.ctx defines, transforms, and propagates context. 4 4 --- 5 5 6 6 + import { Aside } from '@astrojs/starlight/components'; 7 7 + 6 8 7 7 - > Use the Source, Luke: [`modules/context/types.nix`](https://github.com/vic/den/blob/main/modules/context/types.nix) · [`modules/context/os.nix`](https://github.com/vic/den/blob/main/modules/context/os.nix) 9 9 + <Aside title="Use the Source, Luke" icon="github"> 10 10 + [`modules/context/types.nix`](https://github.com/vic/den/blob/main/modules/context/types.nix) · [`modules/context/os.nix`](https://github.com/vic/den/blob/main/modules/context/os.nix) 11 11 + </Aside> 8 12 9 13 ## What Is a Context? 10 14 ··· 30 34 31 35 ## Context Types: den.ctx 32 36 33 33 - Each context type is defined in `den.ctx` with four components: 37 37 + Each context type is defined in `den.ctx`. Context types are 38 38 + [aspect submodules](/explanation/aspects/) — they inherit `includes`, `provides`, 39 39 + `description`, and owned freeform configs from `flake-aspects`'s `aspect` type. 40 40 + **Den adds only the `into` option for context transformations** 34 41 35 42 ```nix 36 43 den.ctx.foobar = { 37 37 - desc = "The {foo, bar} context"; 38 38 - conf = { foo, bar }: den.aspects.${foo}._.${bar}; 44 44 + description = "The {foo, bar} context"; 45 45 + 46 46 + # the aspect responsible for configuring the foobar context 47 47 + provides.foobar = { foo, bar }: den.aspects.${foo}._.${bar}; 48 48 + 49 49 + # foobar contributions to the baz context 50 50 + provides.baz = { baz }: { }; 51 51 + 52 52 + # cutting-point for including other aspects 39 53 includes = [ /* parametric aspects */ ]; 54 54 + 55 55 + # context transformations 40 56 into = { 57 57 + # how to produce baz context from a foobar one. 41 58 baz = { foo, bar }: [{ baz = computeBaz foo bar; }]; 42 59 }; 43 60 }; 44 61 ``` 45 62 63 63 + 46 64 | Component | Purpose | 47 65 |-----------|---------| 48 48 - | `desc` | Human-readable description | 49 49 - | `conf` | Given a context, find aspect responsible for configuration | 66 66 + | `description` | Human-readable description | 67 67 + | `provides.${name}` | Self-named provider: given a context, find aspect responsible for configuration | 68 68 + | `provides.${target}` | Cross-provider: source's contribution to a target context (called per transformation) | 50 69 | `includes` | Parametric aspects activated for this context (aspect cutting-point) | 51 70 | `into` | Transformations fan-out into other context types | 52 71 ··· 58 77 aspect = den.ctx.foobar { foo = "hello"; bar = "world"; }; 59 78 ``` 60 79 61 61 - When applied, Den creates a new aspect that includes the following: 80 80 + When applied, `ctxApply` walks the full `into` graph depth-first, 81 81 + collecting `(source, ctxDef, ctx)` triples, then deduplicates: 62 82 63 63 - 1. **owned configs** from the context itself 64 64 - 2. **main aspect config** via `conf` (e.g., `den.aspects.hello._.world`) 65 65 - 3. **included configs** — parametric aspects matching this context 66 66 - 4. **transforms** — calls each `into` function, producing new contexts 67 67 - 5. **recurses** — applies each produced context through its own pipeline 83 83 + 1. **First visit** to a context type — `fixedTo`: owned + static + parametric dispatch 84 84 + 2. **Subsequent visits** — `atLeast`: parametric dispatch only, **user must take care** 85 85 + 3. **Self-named provider** (`provides.${name}`) is always called when context is used 86 86 + 4. **Cross-provider** (`source.provides.${target}`) is called if the source defines one 68 87 69 88 ```mermaid 70 89 graph TD 71 90 Apply["ctx.foobar { foo, bar }"] 72 72 - Apply --> Own["Owned configs"] 73 73 - Apply --> Conf["ctx → find aspect"] 74 74 - Apply --> Inc["includes → parametric aspects"] 75 75 - Apply --> Into["into.baz → new baz contexts"] 76 76 - Into --> Next["ctx.baz { baz }"] 77 77 - Next --> Own2["...recurse"] 91 91 + Apply --> Collect["collectPairs: walk into graph"] 92 92 + Collect --> Dedup["dedupIncludes: seen-set"] 93 93 + Dedup --> First["1st visit: fixedTo + self + cross"] 94 94 + Dedup --> Later["Nth visit: atLeast + self + cross"] 95 95 + First --> Result["merged includes list"] 96 96 + Later --> Result 78 97 ``` 79 98 80 99 ## Transformation Types ··· 118 137 119 138 ## Contexts as Aspect Cutting-Points 120 139 121 121 - Contexts are aspect-like themselves. They have owned configs and `.includes`: 140 140 + Since context types **are** aspect submodules, they naturally have owned 141 141 + configs and `.includes`: 122 142 123 143 ```nix 124 144 den.ctx.hm-host.nixos.home-manager.useGlobalPkgs = true; ··· 138 158 139 159 ```nix 140 160 den.ctx.hm-host.into.foo = { host }: [ { foo = host.name; } ]; 141 141 - den.ctx.foo.conf = { foo }: { funny.names = [ foo ]; }; 161 161 + den.ctx.foo._.foo = { foo }: { funny.names = [ foo ]; }; 142 162 ``` 143 163 144 164 The module system merges these definitions. You can extend the pipeline ··· 199 219 Create your own for domain-specific pipelines: 200 220 201 221 ```nix 202 202 - den.ctx.greeting.conf = { hello }: 222 222 + den.ctx.greeting._.greeting = { hello }: 203 223 { funny.names = [ hello ]; }; 204 224 205 225 den.ctx.greeting.into.shout = { hello }: 206 226 [{ shout = lib.toUpper hello; }]; 207 227 208 208 - den.ctx.shout.conf = { shout }: 228 228 + den.ctx.shout._.shout = { shout }: 209 229 { funny.names = [ shout ]; }; 210 230 ``` 211 231

+2 -4

docs/src/content/docs/explanation/core-principles.md docs/src/content/docs/explanation/core-principles.mdx

··· 29 29 (hosts, users, homes) and context types (shapes holding them). Den transforms these through 30 30 a graph of context stages, each producing richer or conditioned data. 31 31 32 32 - The key insight: **the flow of data is declared separately from the 33 33 - configurations it produces**. 32 32 + **the flow of data is declared separately from the configurations it produces**. 34 33 35 34 ### 2. Context-Aware Aspects 36 35 ··· 39 38 adapts to every host-user combination. A function requiring `{ other }` is 40 39 not used. 41 40 42 42 - The key insight: **the shape of the function arguments determines when 43 43 - configs are produced, without explicit conditionals**. 41 41 + **the shape of the function arguments determines when configs are produced, without explicit conditionals**. 44 42 45 43 ## Why This Matters 46 44

+4 -3

docs/src/content/docs/explanation/library-vs-framework.md docs/src/content/docs/explanation/library-vs-framework.mdx

··· 3 3 description: Understanding Den's dual nature as both a library and a framework. 4 4 --- 5 5 6 6 + 6 7 ## Den the Library 7 8 8 9 At its core, Den is a **library** for activating configuration aspects via context transformations. ··· 45 46 Here is a deployment pipeline example: 46 47 47 48 ```nix 48 48 - den.ctx.deploy.conf = { target }: 49 49 + den.ctx.deploy._.deploy = { target }: 49 50 den.aspects.${target.name}; 50 51 51 52 den.ctx.deploy.into.service = { target }: 52 53 map (s: { service = s; target = target; }) 53 54 target.services; 54 55 55 55 - den.ctx.service.conf = { service, target }: 56 56 + den.ctx.service._.service = { service, target }: 56 57 { terraform.resource.${service.name} = { ... }; }; 57 58 ``` 58 59 ··· 61 62 2. Targets enumerate their services 62 63 3. Each service produces Terraform configurations 63 64 64 64 - The same `ctxApply` mechanics — owned configs, `conf` lookup, 65 65 + The same `ctxApply` mechanics — owned configs, self-named provider lookup, 65 66 `into` transformations — drive this pipeline without any OS-specific code. 66 67 67 68 You can even design and test custom context flows independently of

+22 -2

docs/src/content/docs/explanation/parametric.md docs/src/content/docs/explanation/parametric.mdx

··· 3 3 description: How parametric functors enable context forwarding and adaptation. 4 4 --- 5 5 6 6 - > Use the source, Luke: [`nix/lib.nix`](https://github.com/vic/den/blob/main/nix/lib.nix) · [`nix/fn-can-take.nix`](https://github.com/vic/den/blob/main/nix/fn-can-take.nix) 6 6 + import { Aside } from '@astrojs/starlight/components'; 7 7 + 8 8 + <Aside title="Use the Source, Luke" icon="github"> 9 9 + [`nix/lib.nix`](https://github.com/vic/den/blob/main/nix/lib.nix) · [`nix/fn-can-take.nix`](https://github.com/vic/den/blob/main/nix/fn-can-take.nix) 10 10 + </Aside> 7 11 8 12 ## What Is a Parametric Aspect? 9 13 ··· 35 39 Den provides several parametric functors in 36 40 `den.lib.parametric`. Each of them provides a 37 41 different `__functor` beaviour. 42 42 + 43 43 + <Aside > 44 44 + Aspects created by Den from your host/user/home definitions are already `parametric`. 45 45 + They will forward context to their includes functions. 46 46 + 47 47 + However for new aspects you define manually, they are not parametric unless you say so. 48 48 + If you get the following error: 49 49 + 50 50 + ```error 51 51 + error: function 'anonymous lambda' called without required argument 'user' 52 52 + ``` 53 53 + 54 54 + It likely means you are trying to forward context from an aspect that is not `parametric`. 55 55 + See also [#182](https://github.com/vic/den/discussions/182) 56 56 + </Aside> 57 57 + 38 58 39 59 ## den.lib.parametric 40 60 ··· 176 196 177 197 ## take.exactly and take.atLeast 178 198 179 179 - For individual functions (not whole aspects), use [`den.lib.take`](/reference/lib/#denlibatake): 199 199 + For individual functions (not whole aspects), use [`den.lib.take`](/reference/lib/#denlibtake): 180 200 181 201 182 202 ```nix

+5 -16

docs/src/content/docs/guides/angle-brackets.md docs/src/content/docs/guides/angle-brackets.mdx

··· 5 5 6 6 import { Aside } from '@astrojs/starlight/components'; 7 7 8 8 - <Aside type="tip">Source: [`nix/den-brackets.nix`](https://github.com/vic/den/blob/main/nix/den-brackets.nix)</Aside> 8 8 + 9 9 + <Aside title="Use the Source, Luke" icon="github">[`nix/den-brackets.nix`](https://github.com/vic/den/blob/main/nix/den-brackets.nix)</Aside> 9 10 10 11 <Aside type="caution">Angle brackets is an experimental, opt-in feature.</Aside> 11 12 ··· 21 22 | `<foo/bar>` | `den.aspects.foo.provides.bar` | 22 23 | `<foo/bar/baz>` | `den.aspects.foo.provides.bar.provides.baz` | 23 24 | `<ns/tools>` | `den.ful.ns.tools` | 24 24 - 25 25 - ## Enable Per-Module 26 26 - 27 27 - Bring `__findFile` into scope from module arguments: 28 28 - 29 29 - ```nix 30 30 - { den, __findFile, ... }: { 31 31 - _module.args.__findFile = den.lib.__findFile; 32 32 - den.aspects.igloo.includes = [ <den/define-user> ]; 33 33 - } 34 34 - ``` 35 25 36 26 ## Enable Globally 37 27 ··· 70 60 With a namespace `ns` enabled: 71 61 72 62 ```nix 73 73 - { __findFile, ns, ... }: { 74 74 - ns.moo.silly = true; 75 75 - # access: 76 76 - expr = <ns/moo>; # resolves to den.ful.ns.moo 63 63 + { __findFile, ... }: { 64 64 + ns.moo.silly = true; # write access 65 65 + expr = <ns/moo>; # read resolves to den.ful.ns.moo 77 66 } 78 67 ``` 79 68

+3 -15

docs/src/content/docs/guides/batteries.md docs/src/content/docs/guides/batteries.mdx

··· 5 5 6 6 import { Aside } from '@astrojs/starlight/components'; 7 7 8 8 - <Aside type="tip">Source: [`modules/aspects/provides/`](https://github.com/vic/den/tree/main/modules/aspects/provides) · Reference: [Batteries](/reference/batteries/)</Aside> 8 8 + <Aside title="Use the Source, Luke" icon="github"> 9 9 + [`modules/aspects/provides/`](https://github.com/vic/den/tree/main/modules/aspects/provides) · Reference: [Batteries](/reference/batteries/) 10 10 + </Aside> 9 11 10 12 ## What Are Batteries? 11 13 ··· 109 111 ``` 110 112 111 113 This is how Home-Manager integration is implemented internally. 112 112 - 113 113 - ## Writing Your Own 114 114 - 115 115 - Any aspect can serve as a battery. Publish it in a namespace for others: 116 116 - 117 117 - ```nix 118 118 - { den, ... }: { 119 119 - den.provides.my-battery = den.lib.parametric { 120 120 - includes = [ 121 121 - ({ host, ... }: { nixos.my-setting = host.name; }) 122 122 - ]; 123 123 - }; 124 124 - } 125 125 - ```

-95

docs/src/content/docs/guides/bidirectional.md

··· 1 1 - --- 2 2 - title: Bidirectional Dependencies 3 3 - description: Hosts configure users and users configure hosts — automatically. 4 4 - --- 5 5 - 6 6 - ## Host → User Configuration 7 7 - 8 8 - A host aspect's `homeManager` settings apply to **all users** on that host: 9 9 - 10 10 - ```nix 11 11 - den.aspects.igloo.homeManager.programs.direnv.enable = true; 12 12 - ``` 13 13 - 14 14 - If `igloo` has users `tux` and `pingu`, both get direnv enabled. 15 15 - 16 16 - This also works with static includes: 17 17 - 18 18 - ```nix 19 19 - den.aspects.igloo.includes = [ 20 20 - { homeManager.programs.direnv.enable = true; } 21 21 - ]; 22 22 - ``` 23 23 - 24 24 - And with parametric includes that receive context: 25 25 - 26 26 - ```nix 27 27 - den.aspects.igloo.includes = [ 28 28 - ({ host, user }: { 29 29 - homeManager.programs.direnv.enable = true; 30 30 - }) 31 31 - ]; 32 32 - ``` 33 33 - 34 34 - ## User → Host Configuration 35 35 - 36 36 - A user aspect's `nixos` or `darwin` settings apply to **every host** with that user: 37 37 - 38 38 - ```nix 39 39 - den.aspects.tux.nixos.programs.fish.enable = true; 40 40 - ``` 41 41 - 42 42 - If `tux` is on both `igloo` and `iceberg`, both hosts get fish enabled. 43 43 - 44 44 - User includes work the same way: 45 45 - 46 46 - ```nix 47 47 - den.aspects.tux.includes = [ 48 48 - ({ host, ... }: { 49 49 - nixos.users.users.tux.description = "Tux on ${host.name}"; 50 50 - }) 51 51 - ]; 52 52 - ``` 53 53 - 54 54 - ## Context-Conditional Bidirectional 55 55 - 56 56 - Combine host and user context for precise control: 57 57 - 58 58 - ```nix 59 59 - let 60 60 - git-on-linux = { user, host, ... }: 61 61 - if !lib.hasSuffix "darwin" host.system 62 62 - then { homeManager.programs.git.enable = true; } 63 63 - else { }; 64 64 - in { 65 65 - den.aspects.tux.includes = [ git-on-linux ]; 66 66 - } 67 67 - ``` 68 68 - 69 69 - User `tux` gets git only on Linux hosts, not on Darwin. 70 70 - 71 71 - ## How It Works 72 72 - 73 73 - ```mermaid 74 74 - graph TD 75 75 - HA["den.aspects.igloo (host)"] -->|"homeManager class"| U1["tux Home-Manager"] 76 76 - HA -->|"homeManager class"| U2["pingu Home-Manager"] 77 77 - UA["den.aspects.tux (user)"] -->|"nixos class"| H1["igloo NixOS"] 78 78 - UA -->|"nixos class"| H2["iceberg NixOS"] 79 79 - ``` 80 80 - 81 81 - Den’s [context system](/explanation/context-system/) handles the routing: 82 82 - - Host aspect configs flow to all users on that host 83 83 - - User aspect configs flow to all hosts with that user 84 84 - - Context functions get called with the specific `{ host, user }` pair 85 85 - 86 86 - ## The `den.default` Backbone 87 87 - 88 88 - Settings in [`den.default`](/explanation/context-pipeline/#dendefault-is-an-alias) apply to **everything** — all hosts and all users: 89 89 - 90 90 - ```nix 91 91 - den.default.homeManager.home.stateVersion = "25.11"; 92 92 - den.default.includes = [ 93 93 - ({ host, ... }: { ${host.class}.networking.hostName = host.name; }) 94 94 - ]; 95 95 - ```

+136

docs/src/content/docs/guides/configure-aspects.mdx

··· 1 1 + --- 2 2 + title: Configure Aspects 3 3 + description: Recipes for configuring aspects — owned configs, includes, providers, and bidirectional dependencies. 4 4 + --- 5 5 + 6 6 + import { Aside } from '@astrojs/starlight/components'; 7 7 + 8 8 + <Aside title="Use the Source, Luke" icon="github"> 9 9 + [`modules/aspects/`](https://github.com/vic/den/tree/main/modules/aspects) · Tests: [`features/user-host-bidirectional-config.nix`](https://github.com/vic/den/blob/main/templates/ci/modules/features/user-host-bidirectional-config.nix) 10 10 + </Aside> 11 11 + 12 12 + ## Static Host Config 13 13 + 14 14 + Set NixOS/Darwin/HM options directly on an aspect: 15 15 + 16 16 + ```nix 17 17 + den.aspects.igloo = { 18 18 + nixos = { pkgs, ... }: { 19 19 + environment.systemPackages = [ pkgs.hello ]; 20 20 + }; 21 21 + homeManager.programs.vim.enable = true; 22 22 + }; 23 23 + ``` 24 24 + 25 25 + ## Include Other Aspects 26 26 + 27 27 + Compose aspects with `includes`: 28 28 + 29 29 + ```nix 30 30 + den.aspects.tux = { 31 31 + includes = [ 32 32 + den.provides.primary-user 33 33 + (den.provides.user-shell "fish") 34 34 + den.aspects.base-tools 35 35 + ]; 36 36 + }; 37 37 + ``` 38 38 + 39 39 + ## Context-Aware Includes 40 40 + 41 41 + Functions in `includes` receive context and only activate when they match: 42 42 + 43 43 + ```nix 44 44 + den.aspects.igloo.includes = [ 45 45 + den.aspects.video 46 46 + ]; 47 47 + 48 48 + den.aspects.video = den.lib.take.exactly ({ host, user }: { 49 49 + nixos.users.users.${user.userName}.extraGroups = [ "video" ]; 50 50 + }); 51 51 + 52 52 + ``` 53 53 + 54 54 + This runs **once per user** on the host. A function taking `{ host }` only runs at the host level. 55 55 + 56 56 + ## Host Configures Its Users 57 57 + 58 58 + A host aspect can contribute to user-level settings: 59 59 + 60 60 + ```nix 61 61 + den.aspects.igloo = { 62 62 + nixos.networking.hostName = "igloo"; 63 63 + homeManager.programs.direnv.enable = true; 64 64 + }; 65 65 + ``` 66 66 + 67 67 + The `homeManager` config from a host aspect becomes the default for **all users** on that host. 68 68 + 69 69 + ## User Configures Its Host 70 70 + 71 71 + A user aspect can contribute to the host's NixOS/Darwin config: 72 72 + 73 73 + ```nix 74 74 + den.aspects.tux = { 75 75 + nixos.users.users.tux.description = "cute penguin"; 76 76 + homeManager = { pkgs, ... }: { 77 77 + home.packages = [ pkgs.htop ]; 78 78 + }; 79 79 + }; 80 80 + ``` 81 81 + 82 82 + The `nixos` config from a user aspect is applied to **every host** the user appears on. 83 83 + 84 84 + 85 85 + ## Conditional Config by Host/User 86 86 + 87 87 + Use aspect arguments to specialize: 88 88 + 89 89 + ```nix 90 90 + den.aspects.igloo.includes = [ den.aspects.tuxGit ]; 91 91 + 92 92 + den.aspects.tuxGit = den.lib.take.exactly ({ host, user }: 93 93 + if user.userName == "tux" 94 94 + then { homeManager.programs.git.enable = true; } 95 95 + else { } 96 96 + ); 97 97 + ``` 98 98 + 99 99 + ## Global Defaults 100 100 + 101 101 + Use `den.default` for settings that apply everywhere: 102 102 + 103 103 + ```nix 104 104 + den.default = { 105 105 + nixos.system.stateVersion = "25.11"; 106 106 + homeManager.home.stateVersion = "25.11"; 107 107 + includes = [ 108 108 + den.provides.define-user 109 109 + (den.lib.take.exactly ({ host }: { 110 110 + nixos.networking.hostName = host.hostName; 111 111 + })) 112 112 + ]; 113 113 + }; 114 114 + ``` 115 115 + 116 116 + Use `den.lib.take.exactly` to restrict a function to a specific context shape (e.g., only at host level, not user level). 117 117 + 118 118 + ## Compose Named Sub-aspects 119 119 + 120 120 + Organize aspects hierarchically using `provides`: 121 121 + 122 122 + ```nix 123 123 + den.aspects.gaming = { 124 124 + nixos.programs.steam.enable = true; 125 125 + provides.emulation.nixos.programs.retroarch.enable = true; 126 126 + provides.streaming = { 127 127 + nixos.services.sunshine.enable = true; 128 128 + homeManager.programs.moonlight.enable = true; 129 129 + }; 130 130 + }; 131 131 + 132 132 + den.aspects.my-pc.includes = [ 133 133 + den.aspects.gaming 134 134 + den.aspects.gaming._.emulation 135 135 + ]; 136 136 + ```

+13 -30

docs/src/content/docs/guides/custom-classes.md docs/src/content/docs/guides/custom-classes.mdx

··· 5 5 6 6 import { Aside } from '@astrojs/starlight/components'; 7 7 8 8 - <Aside type="tip">Source: [`modules/aspects/provides/forward.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/forward.nix) · [CI tests](https://github.com/vic/den/blob/main/templates/ci/modules/forward.nix)</Aside> 8 8 + <Aside title="Use the Source, Luke" icon="github">[`modules/aspects/provides/forward.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/forward.nix) · [CI tests](https://github.com/vic/den/blob/main/templates/ci/modules/forward.nix)</Aside> 9 9 10 10 ## What Are Custom Classes? 11 11 ··· 20 20 21 21 ## Example: Custom Class to NixOS 22 22 23 23 - Forward a `custom` class into NixOS top-level: 23 23 + Forward a new `hjem` class into NixOS top-level: 24 24 25 25 ```nix 26 26 { den, lib, ... }: 27 27 let 28 28 - forwarded = { class, aspect-chain }: 28 28 + hjem = { host }: { class, aspect-chain }: 29 29 den._.forward { 30 30 - each = lib.singleton class; 31 31 - fromClass = _: "custom"; 32 32 - intoClass = _: "nixos"; 33 33 - intoPath = _: [ ]; 34 34 - fromAspect = _: lib.head aspect-chain; 30 30 + each = host.users; 31 31 + fromClass = user: "hjem"; 32 32 + intoClass = user: class; 33 33 + intoPath = user: [ "hjem" "users" user.userName ] 34 34 + fromAspect = user: den.aspects.${user.aspect}; 35 35 }; 36 36 in { 37 37 - den.aspects.igloo = { 38 38 - includes = [ forwarded ]; 39 39 - custom.networking.hostName = "from-custom-class"; 40 40 - }; 37 37 + # host forwards user hjem modules into nixos level. 38 38 + den.aspects.igloo = { includes = [ hjem ]; }; 39 39 + 40 40 + # user aspect has hjem class 41 41 + den.aspects.tux.hjem = { ... }; 41 42 } 42 43 ``` 43 44 44 44 - ## Example: Forward into a Subpath 45 45 - 46 46 - Insert configs into a nested submodule: 47 47 - 48 48 - ```nix 49 49 - den.aspects.igloo = { 50 50 - includes = [ forwarded ]; 51 51 - nixos.imports = [ 52 52 - { options.fwd-box = lib.mkOption { 53 53 - type = lib.types.submoduleWith { modules = [ myModule ]; }; 54 54 - }; } 55 55 - ]; 56 56 - src.items = [ "from-src-class" ]; 57 57 - }; 58 58 - ``` 59 59 - 60 60 - With `intoPath = _: [ "fwd-box" ]`, the `src` class configs merge into 61 61 - `nixos.fwd-box`. 62 45 63 46 ## How Home-Manager Uses Forward 64 47

+4 -11

docs/src/content/docs/guides/debug.md

··· 25 25 }); 26 26 ``` 27 27 28 28 - ## Trace Context Keys 29 29 - 30 30 - See which contexts are being applied: 31 31 - 32 32 - ```nix 33 33 - den.default.includes = [ 34 34 - (context: builtins.trace (builtins.attrNames context) { }) 35 35 - ]; 36 36 - ``` 37 28 38 29 ## REPL Inspection 39 30 ··· 89 80 90 81 ## Common Issues 91 82 92 92 - **Duplicate values in lists**: Your function matches too many contexts. 93 93 - Use `den.lib.take.exactly` to restrict matching: 83 83 + **Duplicate values in lists**: Den automatically deduplicates owned and 84 84 + static configs from `den.default`, but parametric functions in 85 85 + `den.default.includes` still run at every context stage. Use 86 86 + `den.lib.take.exactly` to restrict matching: 94 87 95 88 ```nix 96 89 den.lib.take.exactly ({ host }: { nixos.x = 1; })

+13 -13

docs/src/content/docs/guides/declare-hosts.md docs/src/content/docs/guides/declare-hosts.mdx

··· 5 5 6 6 import { Aside } from '@astrojs/starlight/components'; 7 7 8 8 - <Aside type="tip">Source: [`modules/_types.nix`](https://github.com/vic/den/blob/main/modules/_types.nix) · Reference: [Entity Schema](/reference/schema/)</Aside> 8 8 + <Aside title="Use the Source, Luke" icon="github"> 9 9 + [`modules/_types.nix`](https://github.com/vic/den/blob/main/modules/_types.nix) · Reference: [Entity Schema](/reference/schema/) 10 10 + </Aside> 9 11 10 12 ## Hosts and Users 11 13 ··· 16 18 den.hosts.aarch64-darwin.macbook.users.vic = { }; 17 19 ``` 18 20 19 19 - This creates NixOS/Darwin configurations with users, ready for: 21 21 + This creates NixOS/Darwin configurations with users sharing the same home configuration, ready for: 20 22 21 23 ```console 22 24 nixos-rebuild switch --flake .#my-laptop ··· 74 76 ```nix 75 77 den.hosts.x86_64-linux.my-laptop = { 76 78 isWarm = true; # custom attribute 77 77 - location = "home"; # custom attribute 79 79 + location = "studio"; # custom attribute 78 80 users.vic = { }; 79 81 }; 80 82 ``` ··· 103 105 104 106 ## Custom Instantiation 105 107 106 106 - Override how configurations are built: 108 108 + Different `nixpkgs` channels per host: 107 109 108 110 ```nix 109 109 - den.hosts.x86_64-linux.wsl-box = { 110 110 - class = "nixos"; 111 111 - instantiate = inputs.nixos-wsl.lib.nixosSystem; 112 112 - intoAttr = "wslConfigurations"; 113 113 - users.vic = { }; 111 111 + den.hosts.x86_64-linux.stable-server = { 112 112 + instantiate = inputs.nixpkgs-stable.lib.nixosSystem; 113 113 + users.admin = { }; 114 114 }; 115 115 ``` 116 116 117 117 - Different `nixpkgs` channels per host: 117 117 + Override where configurations are placed: 118 118 119 119 ```nix 120 120 - den.hosts.x86_64-linux.stable-server = { 121 121 - instantiate = inputs.nixpkgs-stable.lib.nixosSystem; 122 122 - users.admin = { }; 120 120 + den.hosts.x86_64-linux.wsl-box = { 121 121 + intoAttr = "wslConfigurations"; 122 122 + users.wsl = { }; 123 123 }; 124 124 ```

+4 -1

docs/src/content/docs/guides/home-manager.md docs/src/content/docs/guides/home-manager.mdx

··· 3 3 description: Integrate Home-Manager into NixOS/Darwin hosts or use standalone. 4 4 --- 5 5 6 6 + 6 7 import { Aside } from '@astrojs/starlight/components'; 7 8 8 8 - <Aside type="tip">Source: [`hm-os.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/hm-os.nix) · [`hm-integration.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/hm-integration.nix)</Aside> 9 9 + <Aside title="Use the Source, Luke" icon="github"> 10 10 + [`hm-os.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/hm-os.nix) · [`hm-integration.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/hm-integration.nix) 11 11 + </Aside> 9 12 10 13 ## Automatic HM Detection 11 14

+15 -5

docs/src/content/docs/guides/namespaces.md docs/src/content/docs/guides/namespaces.mdx

··· 5 5 6 6 import { Aside } from '@astrojs/starlight/components'; 7 7 8 8 - <Aside type="tip">Source: [`nix/namespace.nix`](https://github.com/vic/den/blob/main/nix/namespace.nix)</Aside> 8 8 + <Aside title="Use the Source, Luke" icon="github">[`nix/namespace.nix`](https://github.com/vic/den/blob/main/nix/namespace.nix)</Aside> 9 9 10 10 ## What Are Namespaces? 11 11 12 12 Namespaces let you organize aspects into named collections that can be 13 13 shared across flakes and consumed by others. 14 14 15 15 + This is unlike your `den.aspects.<name>` namespace which is private, 16 16 + because you wont likely want to share your user/host configurations. 17 17 + 18 18 + Namespaces are for re-usable aspects you are willing to share with others. 19 19 + 15 20 ## Define a Local Namespace 16 21 17 22 ```nix ··· 21 26 } 22 27 ``` 23 28 29 29 + The first argument is the aspect namespace name. 30 30 + It will be provided as module argument: `{ lib, ns, ... }` 31 31 + so you can access aspects from the namespace. 32 32 + 24 33 The second argument controls output: 25 34 - `false` — local only, not exposed as flake output 26 35 - `true` — exposed at `flake.denful.ns` ··· 28 37 29 38 ## Consume Remote Namespaces 30 39 31 31 - Import aspects from another flake's `denful` output: 40 40 + Import aspects from another flake's `flake.denful.provider` output: 32 41 33 42 ```nix 34 43 { inputs, ... }: { ··· 40 49 } 41 50 ``` 42 51 43 43 - Multiple sources are merged. Local definitions override remote ones. 52 52 + Multiple sources are merged by the module system. 44 53 45 54 ## Nested Provides in Namespaces 46 55 ··· 92 101 angle brackets: 93 102 94 103 ```nix 95 95 - { __findFile, ns, ... }: { 104 104 + { __findFile, ... }: { 96 105 _module.args.__findFile = den.lib.__findFile; 106 106 + 97 107 den.aspects.igloo.includes = [ <ns/tools> ]; 98 108 } 99 109 ``` 100 110 101 111 ## Real-World: denful 102 112 103 103 - [denful](https://github.com/vic/denful) is a community aspect distribution 113 113 + [denful](https://github.com/vic/denful) is a (WIP) community aspect distribution 104 114 built on Den namespaces — a lazyvim-like approach to Nix configurations.

-91

docs/src/content/docs/guides/no-flakes.md

··· 1 1 - --- 2 2 - title: Use Without Flakes 3 3 - description: Den works with stable Nix, npins, and without flake-parts. 4 4 - --- 5 5 - 6 6 - ## Den is Flake-Agnostic 7 7 - 8 8 - Den does **not** require Nix flakes. It works with: 9 9 - 10 10 - - Nix flakes + flake-parts (most common) 11 11 - - Nix flakes without flake-parts 12 12 - - No flakes at all (stable Nix + npins or fetchTarball) 13 13 - 14 14 - ## Without Flakes 15 15 - 16 16 - Use `flake-compat` to evaluate Den from a non-flake setup: 17 17 - 18 18 - ```nix 19 19 - # default.nix 20 20 - let 21 21 - flake = import (fetchTarball { 22 22 - url = "https://github.com/edolstra/flake-compat/archive/...tar.gz"; 23 23 - }) { src = ./.; }; 24 24 - in 25 25 - flake.outputs 26 26 - ``` 27 27 - 28 28 - See the [`noflake` template](https://github.com/vic/den/tree/main/templates/noflake) 29 29 - for a complete working example with npins. 30 30 - 31 31 - ## Without Flake-Parts 32 32 - 33 33 - Den provides its own minimal `flake` option when flake-parts is not present. 34 34 - Simply import `inputs.den.flakeModule`: 35 35 - 36 36 - ```nix 37 37 - let 38 38 - denCfg = (lib.evalModules { 39 39 - modules = [ 40 40 - (import-tree ./modules) 41 41 - inputs.den.flakeModule 42 42 - ]; 43 43 - specialArgs = { inherit inputs; }; 44 44 - }).config; 45 45 - in { 46 46 - nixosConfigurations.igloo = 47 47 - denCfg.flake.nixosConfigurations.igloo; 48 48 - } 49 49 - ``` 50 50 - 51 51 - ## With Flake-Parts 52 52 - 53 53 - The standard setup — Den integrates seamlessly: 54 54 - 55 55 - ```nix 56 56 - { 57 57 - outputs = inputs: 58 58 - inputs.flake-parts.lib.mkFlake { inherit inputs; } 59 59 - (inputs.import-tree ./modules); 60 60 - 61 61 - inputs = { 62 62 - den.url = "github:vic/den"; 63 63 - flake-aspects.url = "github:vic/flake-aspects"; 64 64 - import-tree.url = "github:vic/import-tree"; 65 65 - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; 66 66 - flake-parts.url = "github:hercules-ci/flake-parts"; 67 67 - }; 68 68 - } 69 69 - ``` 70 70 - 71 71 - ## The Dendritic Module 72 72 - 73 73 - For flake-parts users who want automatic Den + flake-aspects setup: 74 74 - 75 75 - ```nix 76 76 - imports = [ inputs.den.flakeModules.dendritic ]; 77 77 - ``` 78 78 - 79 79 - This auto-configures `flake-file` inputs for `den` and `flake-aspects`. 80 80 - 81 81 - ## Minimal Dependencies 82 82 - 83 83 - Den's only hard dependency is `flake-aspects`. Everything else is optional: 84 84 - 85 85 - | Dependency | Required? | Purpose | 86 86 - |-----------|-----------|---------| 87 87 - | `flake-aspects` | **Yes** | [Aspect composition](https://github.com/vic/flake-aspects) | 88 88 - | `import-tree` | Optional | [Auto-import module directories](https://github.com/vic/import-tree) | 89 89 - | `flake-parts` | Optional | Flake structuring | 90 90 - | `nixpkgs` | Optional | Only if building NixOS/HM configs | 91 91 - | `home-manager` | Optional | Only if using HM integration |

+3 -3

docs/src/content/docs/index.mdx

··· 9 9 <img width="400" height="400" src="https://github.com/user-attachments/assets/af9c9bca-ab8b-4682-8678-31a70d510bbb" /> 10 10 actions: 11 11 - text: NixOS Framework 12 12 - link: /tutorials/getting-started/ 12 12 + link: /tutorials/overview/ 13 13 icon: right-arrow 14 14 - text: Pure Nix Library 15 15 link: /explanation/library-vs-framework ··· 137 137 # generic config for all hosts, users, homes. 138 138 den.default.nixos.system.stateVersion = "25.11"; 139 139 den.default.homeManager.home.stateVersion = "25.11"; 140 140 - den.default.includes [ den._.inputs' ]; 140 140 + den.default.includes = [ den._.inputs' ]; 141 141 142 142 } 143 143 ``` ··· 150 150 </Card> 151 151 <Card title="Bidirectional" icon="right-arrow"> 152 152 Hosts configure their users. Users contribute to their 153 153 - hosts. [Aspects flow in both directions](/guides/bidirectional/) automatically. 153 153 + hosts. [Aspects flow in both directions](/guides/configure-aspects/) automatically. 154 154 </Card> 155 155 <Card title="Batteries Included" icon="add-document"> 156 156 Opt-in [aspects for common tasks](/guides/batteries/): define-user, primary-user,

+20 -12

docs/src/content/docs/motivation.md docs/src/content/docs/motivation.mdx

··· 3 3 description: The motivation and fundamental idea behind Den. 4 4 --- 5 5 6 6 + import { Aside } from '@astrojs/starlight/components'; 6 7 7 7 - > This section is about how and why Den came to be. 8 8 - > You can safely skip this unless you are interested in how Den was shaped. 9 9 - > 10 10 - > However you might need to already be familiar with what [Dendritic](https://github.com/mightyiam/dendritic) means 11 11 - > you might also want to read the [FAQ](https://github.com/Doc-Steve/dendritic-design-with-flake-parts/wiki/FAQ) 8 8 + <Aside> 9 9 + This section is about how and why Den came to be. 10 10 + You can safely skip this unless you are interested in how Den was shaped. 11 11 + 12 12 + However you might need to already be familiar with what [Dendritic](https://github.com/mightyiam/dendritic) means 13 13 + you might also want to read the [FAQ](https://github.com/Doc-Steve/dendritic-design-with-flake-parts/wiki/FAQ) 14 14 + </Aside> 12 15 13 16 Den is basically about a single idea: 14 17 15 15 - > Being able to share re-usable (parametric) cross-class Nix configurations. 18 18 + <Aside type="tip" icon="star" title="Motivation"> 19 19 + Den was built for being able to share re-usable (parametric) cross-class Nix configurations. 20 20 + </Aside> 16 21 17 22 Den was born not to be yet-another zillionth way to wire-up configurations. 18 23 ··· 32 37 At that time [unify](https://codeberg.org/quasigod/unify) - the first dendritic framework I know of- entered my radar, and I really loved it! It was missing a couple of features that I needed in my existing infra, but I loved the `<aspect>.<class>` transposition that its author invented, and the cleaness of the code at the author's infra was a testament to how good-looking and organized a Dendritic setup could look. I certainly wanted that for mine. 33 38 34 39 However, before adopting `unify`, I realized that my re-usability problem was not about syntax, not about how things are loaded from filesystem nor how they are wired at the flake level. 35 35 - 36 36 - > The problem was more about feature composability. 40 40 + **The problem was more about feature composability.** 37 41 38 42 Being an fan of functional programming, the most composable things I know are functions. 39 43 ··· 59 63 An important point is that parametric aspect's context **are not** _module.args, they do not depend on config. This allows using them for [conditional](https://github.com/vic/den/blob/main/templates/ci/modules/features/conditional-config.nix) imports. 60 64 61 65 62 62 - > Some [people](https://codeberg.org/FrdrCkII/nixconf/src/branch/main/modules/aspects.prt.nix) have found `flake-aspects` enough to implement their own Dendritic setups, or even for mixing with other non-dendritic infra. 66 66 + <Aside> 67 67 + Some [people](https://codeberg.org/FrdrCkII/nixconf/src/branch/main/modules/aspects.prt.nix) have found [`flake-aspects`](https://github.com/vic/flake-aspects) enough to implement their own Dendritic setups, or even for mixing with other non-dendritic infra. 68 68 + </Aside> 63 69 64 70 ## Den builds upon flake-aspects 65 71 ··· 77 83 78 84 `den.default.includes = [ (den._.unfree ["vscode"]) ]` 79 85 80 80 - - How a `Host` can affect its `User`s configurations, and [viceversa](/guides/bidirectional). 86 86 + - How a `Host` can affect its `User`s configurations, and [viceversa](/guides/configure-aspects). 81 87 82 88 - How to [mixin](/guides/namespaces) aspects from remote sources and enhance locally defined ones. 83 89 ··· 98 104 99 105 Den is more about giving to others (creating useful Nix software/configurations), not just about make things work locally. 100 106 101 101 - > I've been working over a year on these [dendritic libs](https://vic.github.io/dendrix/Dendritic-Ecosystem.html#vics-dendritic-libraries), but time is our most scarce resource. If you like my work, consider [sponsoring](https://github.com/sponsors/vic) 107 107 + <Aside type="tip" title="Support Den development" icon="heart"> 108 108 + I've been working over a year on these [dendritic libs](https://vic.github.io/dendrix/Dendritic-Ecosystem.html#vics-dendritic-libraries), but time is our most scarce resource. If you like my work, consider [sponsoring](https://github.com/sponsors/vic) 109 109 + </Aside> 102 110 103 111 104 112 ## What's Next? 105 113 106 106 - Ready to try it? Head to the [Getting Started](/tutorials/getting-started/) tutorial. 114 114 + Ready to try it? Head to the [Templates overview](/tutorials/overview/) to pick a starting point. 107 115 108 116 Want to understand the architecture? Read about the [Core Principles](/explanation/core-principles/).

-127

docs/src/content/docs/reference/aspects.md

··· 1 1 - --- 2 2 - title: den.aspects Reference 3 3 - description: Aspect structure, resolution, and configuration. 4 4 - --- 5 5 - 6 6 - import { Aside } from '@astrojs/starlight/components'; 7 7 - 8 8 - <Aside type="tip">Source: [`modules/aspects.nix`](https://github.com/vic/den/blob/main/modules/aspects.nix) · [`modules/aspects/definition.nix`](https://github.com/vic/den/blob/main/modules/aspects/definition.nix) · [`modules/aspects/provides.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides.nix)</Aside> 9 9 - 10 10 - ## Aspect Attributes 11 11 - 12 12 - Every aspect is an attribute set with these recognized keys: 13 13 - 14 14 - | Attribute | Type | Description | 15 15 - |-----------|------|-------------| 16 16 - | `nixos` | module | NixOS configuration module | 17 17 - | `darwin` | module | nix-darwin configuration module | 18 18 - | `homeManager` | module | Home-Manager configuration module | 19 19 - | `<class>` | module | Any custom Nix class | 20 20 - | `includes` | list | Dependencies on other aspects or functions | 21 21 - | `provides` | attrset | Nested sub-aspects | 22 22 - | `_` | alias | Shorthand for `provides` | 23 23 - | `description` | str | Human-readable description | 24 24 - | `__functor` | function | Context-aware behavior | 25 25 - 26 26 - ## Automatic Aspect Creation 27 27 - 28 28 - Den creates an aspect for each host, user, and home you declare: 29 29 - 30 30 - ```nix 31 31 - den.hosts.x86_64-linux.igloo.users.tux = { }; 32 32 - # Creates: den.aspects.igloo and den.aspects.tux 33 33 - ``` 34 34 - 35 35 - Aspects are created with `parametric { <class> = {}; }` functor 36 36 - matching the entity's class. 37 37 - 38 38 - ## Aspect Resolution 39 39 - 40 40 - To extract a class module from an aspect: 41 41 - 42 42 - ```nix 43 43 - module = aspect.resolve { class = "nixos"; aspect-chain = []; }; 44 44 - ``` 45 45 - 46 46 - Resolution collects the specified class from the aspect and all 47 47 - transitive includes into a single merged Nix module. 48 48 - 49 49 - ## den.aspects (option) 50 50 - 51 51 - ```nix 52 52 - options.den.aspects = lib.mkOption { 53 53 - type = aspectsType; 54 54 - default = { }; 55 55 - }; 56 56 - ``` 57 57 - 58 58 - Contributions from any module are merged: 59 59 - 60 60 - ```nix 61 61 - # file1.nix 62 62 - den.aspects.igloo.nixos.networking.hostName = "igloo"; 63 63 - 64 64 - # file2.nix 65 65 - den.aspects.igloo.homeManager.programs.vim.enable = true; 66 66 - ``` 67 67 - 68 68 - ## den.provides (batteries) 69 69 - 70 70 - ```nix 71 71 - options.den.provides = lib.mkOption { 72 72 - type = lib.types.submodule { 73 73 - freeformType = lib.types.attrsOf providerType; 74 74 - }; 75 75 - }; 76 76 - ``` 77 77 - 78 78 - Access via `den._.name` or `den.provides.name`. 79 79 - See [Batteries Reference](/reference/batteries/) for all built-in aspects. 80 80 - 81 81 - ## den.default 82 82 - 83 83 - The global dispatcher aspect: 84 84 - 85 85 - ```nix 86 86 - den.default = den.lib.parametric.atLeast { }; 87 87 - ``` 88 88 - 89 89 - All hosts, users, and homes include `den.default`. Set global 90 90 - configs and shared [parametric](/explanation/parametric/) includes here. 91 91 - 92 92 - Aliased from `den.ctx.default`. 93 93 - 94 94 - ## Including Aspects 95 95 - 96 96 - ```nix 97 97 - den.aspects.igloo.includes = [ 98 98 - # another aspect 99 99 - den.aspects.gaming 100 100 - 101 101 - # nested provides 102 102 - den.aspects.tools._.editors 103 103 - 104 104 - # static config 105 105 - { homeManager.programs.direnv.enable = true; } 106 106 - 107 107 - # context function 108 108 - ({ host, ... }: { nixos.time.timeZone = "UTC"; }) 109 109 - 110 110 - # battery 111 111 - den._.define-user 112 112 - 113 113 - # battery with args 114 114 - (den._.user-shell "fish") 115 115 - (den._.unfree [ "discord" ]) 116 116 - ]; 117 117 - ``` 118 118 - 119 119 - ## Aspect as Module Argument 120 120 - 121 121 - `den` is available as a module argument in all Den modules: 122 122 - 123 123 - ```nix 124 124 - { den, ... }: { 125 125 - den.aspects.foo = den.lib.parametric { ... }; 126 126 - } 127 127 - ```

+74

docs/src/content/docs/reference/aspects.mdx

··· 1 1 + --- 2 2 + title: den.aspects Reference 3 3 + description: Aspect structure, resolution, and configuration. 4 4 + --- 5 5 + 6 6 + import { Aside } from '@astrojs/starlight/components'; 7 7 + 8 8 + <Aside title="Use the Source, Luke" icon="github">[`modules/aspects.nix`](https://github.com/vic/den/blob/main/modules/aspects.nix) · [`modules/aspects/definition.nix`](https://github.com/vic/den/blob/main/modules/aspects/definition.nix) · [`modules/aspects/provides.nix`](https://github.com/vic/den/blob/main/modules/aspects/provides.nix) · Tests: [`user-host-bidirectional-config.nix`](https://github.com/vic/den/blob/main/templates/ci/modules/features/user-host-bidirectional-config.nix) · [`top-level-parametric.nix`](https://github.com/vic/den/blob/main/templates/ci/modules/features/top-level-parametric.nix)</Aside> 9 9 + 10 10 + ## Aspect Attributes 11 11 + 12 12 + Every aspect is an attribute set with these recognized keys: 13 13 + 14 14 + | Attribute | Type | Description | 15 15 + |-----------|------|-------------| 16 16 + | `description` | str | Human-readable description | 17 17 + | `__functor` | function | Context-aware behavior | 18 18 + | `includes` | list | Dependencies on other aspects or functions | 19 19 + | `provides` | attrset | Nested sub-aspects | 20 20 + | `_` | alias | Shorthand for `provides` | 21 21 + | `<class>` | module | Any Nix class, like the following | 22 22 + | `nixos` | module | NixOS configuration module | 23 23 + | `darwin` | module | nix-darwin configuration module | 24 24 + | `homeManager` | module | Home-Manager configuration module | 25 25 + 26 26 + ## Automatic Aspect Creation 27 27 + 28 28 + Den creates an aspect for each host, user, and home you declare: 29 29 + 30 30 + ```nix 31 31 + den.hosts.x86_64-linux.igloo.users.tux = { }; 32 32 + 33 33 + # will create: 34 34 + 35 35 + den.aspects.igloo = parametric { }; 36 36 + den.aspects.tux = parametric { }; 37 37 + ``` 38 38 + 39 39 + ## Aspect Resolution 40 40 + 41 41 + To extract a class module from an aspect use the flake-aspects API: 42 42 + 43 43 + ```nix 44 44 + module = aspect.resolve { class = "nixos"; aspect-chain = []; }; 45 45 + ``` 46 46 + 47 47 + Resolution collects the specified class from the aspect and all 48 48 + transitive includes into a single merged Nix module. 49 49 + 50 50 + ## den.aspects (namespace) 51 51 + 52 52 + This namespace is where Den creates aspects for your host/user/home. 53 53 + 54 54 + You can also use this namespace to create your own aspects. 55 55 + Aspects in this namespace are not shared outside the flake, 56 56 + for that use `den.namespace`. 57 57 + 58 58 + Contributions from any module are merged: 59 59 + 60 60 + ```nix 61 61 + # file1.nix 62 62 + den.aspects.igloo.nixos.networking.hostName = "igloo"; 63 63 + 64 64 + # file2.nix 65 65 + den.aspects.igloo.homeManager.programs.vim.enable = true; 66 66 + ``` 67 67 + 68 68 + ## den.provides (namespace) 69 69 + 70 70 + Den batteries-included re-usable aspects. 71 71 + 72 72 + Access via `den._.name` or `den.provides.name`. 73 73 + 74 74 + See [Batteries Reference](/reference/batteries/) for all built-in aspects.

+12 -7

docs/src/content/docs/reference/batteries.md docs/src/content/docs/reference/batteries.mdx

··· 5 5 6 6 import { Aside } from '@astrojs/starlight/components'; 7 7 8 8 - <Aside type="tip">Source: [`modules/aspects/provides/`](https://github.com/vic/den/tree/main/modules/aspects/provides)</Aside> 8 8 + <Aside title="Use the Source, Luke" icon="github">[`modules/aspects/provides/`](https://github.com/vic/den/tree/main/modules/aspects/provides) · Tests: [`batteries/`](https://github.com/vic/den/tree/main/templates/ci/modules/features/batteries)</Aside> 9 9 10 10 ## Overview 11 11 ··· 15 15 ## define-user 16 16 17 17 Defines a user at OS and Home-Manager levels. 18 18 - ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/define-user.nix)) 18 18 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/define-user.nix) · [tests](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/define-user.nix)) 19 19 20 20 ```nix 21 21 den.default.includes = [ den._.define-user ]; ··· 31 31 ## primary-user 32 32 33 33 Makes a user an administrator. 34 34 - ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/primary-user.nix)) 34 34 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/primary-user.nix) · [tests](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/primary-user.nix)) 35 35 36 36 ```nix 37 37 den.aspects.vic.includes = [ den._.primary-user ]; ··· 47 47 ## user-shell 48 48 49 49 Sets default shell at OS and HM levels. 50 50 - ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/user-shell.nix)) 50 50 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/user-shell.nix) · [tests](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/user-shell.nix)) 51 51 52 52 ```nix 53 53 den.aspects.vic.includes = [ (den._.user-shell "fish") ]; ··· 63 63 ## unfree 64 64 65 65 Enables unfree packages by name. 66 66 - ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/unfree/unfree-predicate-builder.nix) · [predicate](https://github.com/vic/den/blob/main/modules/aspects/provides/unfree/unfree.nix)) 66 66 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/unfree/unfree-predicate-builder.nix) · [predicate](https://github.com/vic/den/blob/main/modules/aspects/provides/unfree/unfree.nix) · [tests](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/unfree.nix)) 67 67 68 68 ```nix 69 69 den.aspects.laptop.includes = [ (den._.unfree [ "discord" ]) ]; ··· 82 82 ## tty-autologin 83 83 84 84 Automatic tty login. 85 85 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/tty-autologin.nix) · [tests](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/tty-autologin.nix)) 85 86 86 87 ```nix 87 88 den.aspects.laptop.includes = [ (den._.tty-autologin "root") ]; ··· 94 95 ## import-tree 95 96 96 97 Auto-imports non-dendritic Nix files by class directory. 97 97 - ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/import-tree.nix)) 98 98 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/import-tree.nix) · [tests](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/import-tree.nix)) 98 99 99 100 ```nix 100 101 den.aspects.laptop.includes = [ (den._.import-tree ./path) ]; ··· 115 116 ## inputs' (flake-parts) 116 117 117 118 Provides per-system `inputs'` as a module argument. 119 119 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/flake-parts/inputs.nix) · [tests](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/flake-parts.nix)) 118 120 119 121 ```nix 120 122 den.default.includes = [ den._.inputs' ]; ··· 125 127 ## self' (flake-parts) 126 128 127 129 Provides per-system `self'` as a module argument. 130 130 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/flake-parts/self.nix) · [tests](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/flake-parts.nix)) 128 131 129 132 ```nix 130 133 den.default.includes = [ den._.self' ]; ··· 135 138 ## forward 136 139 137 140 Creates custom Nix classes by forwarding configs between classes. 138 138 - ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/forward.nix) · [usage guide](/guides/custom-classes/)) 141 141 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/forward.nix) · [tests](https://github.com/vic/den/blob/main/templates/ci/modules/features/forward.nix) · [usage guide](/guides/custom-classes/)) 139 142 140 143 ```nix 141 144 den._.forward { ··· 154 157 HM integration is handled by 155 158 `den.ctx.hm-host` and `den.ctx.hm-user` context types, which are 156 159 activated automatically when hosts have HM users. 160 160 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/home-manager/) · [tests](https://github.com/vic/den/blob/main/templates/ci/modules/features/home-manager/)) 157 161 158 162 All `homeManager` class settings are forwarded to os-level `home-manager.users.<userName>`. 159 163 160 164 ## user 161 165 162 166 The `user` class is automatically handled by Den and forwards to os-level `users.users.<userName>` 167 167 + ([source](https://github.com/vic/den/blob/main/modules/aspects/provides/os-user.nix)) 163 168 164 169 You can write: 165 170

-180

docs/src/content/docs/reference/ctx.md

··· 1 1 - --- 2 2 - title: den.ctx Reference 3 3 - description: Context type definitions and their built-in implementations. 4 4 - --- 5 5 - 6 6 - import { Aside } from '@astrojs/starlight/components'; 7 7 - 8 8 - <Aside type="tip">Source: [`modules/context/types.nix`](https://github.com/vic/den/blob/main/modules/context/types.nix) · [`modules/context/os.nix`](https://github.com/vic/den/blob/main/modules/context/os.nix) · [`modules/aspects/defaults.nix`](https://github.com/vic/den/blob/main/modules/aspects/defaults.nix)</Aside> 9 9 - 10 10 - ## Context Type Schema 11 11 - 12 12 - Each `den.ctx.<name>` is a submodule with these options: 13 13 - 14 14 - | Option | Type | Description | 15 15 - |--------|------|-------------| 16 16 - | `desc` | `str` | Human-readable description | 17 17 - | `conf` | `ctx → aspect` | Locates the aspect for this context | 18 18 - | `into` | `attrset of (ctx → list)` | Transformations to other contexts | 19 19 - | `includes` | `list of aspect` | Parametric aspects activated for this context | 20 20 - 21 21 - Context types are also functors — callable as functions: 22 22 - 23 23 - ```nix 24 24 - aspect = den.ctx.host { host = den.hosts.x86_64-linux.igloo; }; 25 25 - ``` 26 26 - 27 27 - ## ctxApply (internal) 28 28 - 29 29 - When a context type is applied, `ctxApply` executes: 30 30 - 31 31 - ```nix 32 32 - ctxApply = self: ctx: { 33 33 - includes = lib.flatten [ 34 34 - (parametric.fixedTo ctx (cleanCtx self)) # owned configs 35 35 - (self.conf ctx) # located aspect 36 36 - (mapAttrsToList (name: into: # transformations 37 37 - map den.ctx.${name} (into ctx) 38 38 - ) self.into) 39 39 - ]; 40 40 - }; 41 41 - ``` 42 42 - 43 43 - ## Transformation Types 44 44 - 45 45 - All `into` transformations have the type `source → [ target ]`: 46 46 - 47 47 - - **Fan-out**: `{ host }: map (u: { inherit host user; }) users` — one host produces N contexts 48 48 - - **Conditional**: `{ host }: lib.optional (test host) { inherit host; }` — zero or one 49 49 - - **Pass-through**: `lib.singleton` — forward the same data as-is 50 50 - 51 51 - An empty list means the target context is not created. This enables 52 52 - conditional activation like HM detection without any explicit `if` logic 53 53 - in the pipeline. 54 54 - 55 55 - ## Contexts as Cutting-Points 56 56 - 57 57 - Context types have their own owned configs and `includes`, making them 58 58 - aspect-like cutting-points in the pipeline: 59 59 - 60 60 - ```nix 61 61 - den.ctx.hm-host.nixos.home-manager.useGlobalPkgs = true; 62 62 - den.ctx.hm-host.includes = [ 63 63 - ({ host, ... }: { nixos.home-manager.backupFileExtension = "bak"; }) 64 64 - ]; 65 65 - ``` 66 66 - 67 67 - These only activate for validated HM hosts — more precise than 68 68 - `den.default.includes` which runs at every pipeline stage. 69 69 - 70 70 - ## Extending Context Flow 71 71 - 72 72 - Add transformations to existing context types from any module: 73 73 - 74 74 - ```nix 75 75 - den.ctx.hm-host.into.foo = { host }: [ { foo = host.name; } ]; 76 76 - den.ctx.foo.conf = { foo }: { funny.names = [ foo ]; }; 77 77 - ``` 78 78 - 79 79 - The module system merges these definitions. You can also override a 80 80 - host's `mainModule` to use a completely custom context flow. 81 81 - 82 82 - ## Built-in Context Types 83 83 - 84 84 - ### den.ctx.host 85 85 - 86 86 - | Field | Value | 87 87 - |-------|-------| 88 88 - | `desc` | OS | 89 89 - | `conf` | `{ host }:` fixedTo host aspect | 90 90 - | `into.default` | `lib.singleton` (pass-through) | 91 91 - | `into.user` | Enumerate `host.users` | 92 92 - | `into.hm-host` | Detect HM support (from `hm-detect.nix`) | 93 93 - 94 94 - ### den.ctx.user 95 95 - 96 96 - | Field | Value | 97 97 - |-------|-------| 98 98 - | `desc` | OS user | 99 99 - | `conf` | `{ host, user }:` includes user + host aspects | 100 100 - | `into.default` | `lib.singleton` (pass-through) | 101 101 - 102 102 - ### den.ctx.default 103 103 - 104 104 - | Field | Value | 105 105 - |-------|-------| 106 106 - | `conf` | `_: { }` (empty — just a dispatcher) | 107 107 - 108 108 - Aliased as `den.default` via `lib.mkAliasOptionModule`. 109 109 - Writing `den.default.foo` is identical to `den.ctx.default.foo`. 110 110 - 111 111 - Every context type transforms into `default`, so `den.default.includes` 112 112 - functions run at every pipeline stage. Use `take.exactly` to restrict 113 113 - matching if you see duplicate values. 114 114 - 115 115 - ### den.ctx.home 116 116 - 117 117 - | Field | Value | 118 118 - |-------|-------| 119 119 - | `desc` | Standalone Home-Manager config | 120 120 - | `conf` | `{ home }:` fixedTo home aspect | 121 121 - | `into.default` | `lib.singleton` | 122 122 - 123 123 - ### den.ctx.hm-host 124 124 - 125 125 - | Field | Value | 126 126 - |-------|-------| 127 127 - | `desc` | Host with HM-supported OS and HM users | 128 128 - | `conf` | `{ host }:` imports HM NixOS/Darwin module | 129 129 - | `into.hm-user` | Enumerate HM-class users | 130 130 - 131 131 - **Detection criteria** (all must be true): 132 132 - 1. Host class is `nixos` or `darwin` 133 133 - 2. At least one user has `class = "homeManager"` 134 134 - 3. `inputs.home-manager` exists, or host has a custom `hm-module` attribute 135 135 - 136 136 - If detection fails, the HM pipeline is skipped entirely. 137 137 - 138 138 - ### den.ctx.hm-user 139 139 - 140 140 - | Field | Value | 141 141 - |-------|-------| 142 142 - | `desc` | Internal — forwards HM class to host | 143 143 - | `conf` | `{ host, user }:` forward homeManager into host | 144 144 - 145 145 - ### den.ctx.hm-internal-user (internal) 146 146 - 147 147 - An internal context type used by `hm-user`. It combines: 148 148 - - The user context (`den.ctx.user { host, user }`) 149 149 - - Owned configs from the host aspect 150 150 - - Static includes from the host aspect 151 151 - - Parametric includes from the host aspect matching `{ host, user }` 152 152 - 153 153 - This ensures that when the `homeManager` class is forwarded into 154 154 - `home-manager.users.<name>`, it receives contributions from both 155 155 - the user's aspect and the host's aspect. 156 156 - 157 157 - ## Defining Custom Context Types 158 158 - 159 159 - Context types are independent of NixOS. Use them for any domain: 160 160 - 161 161 - ```nix 162 162 - den.ctx.myctx = { 163 163 - desc = "{x, y} context"; 164 164 - conf = { x, y }: { funny.names = [ x y ]; }; 165 165 - includes = [ 166 166 - ({ x, ... }: { funny.names = [ "include-${x}" ]; }) 167 167 - ]; 168 168 - into = { 169 169 - other = { x, y }: [{ z = x + y; }]; 170 170 - }; 171 171 - }; 172 172 - ``` 173 173 - 174 174 - Owned attributes (anything not `desc`, `conf`, `into`, `includes`) 175 175 - are included when the context is applied. 176 176 - 177 177 - Custom context flows can be designed and tested in isolation — Den's 178 178 - CI tests use a `funny.names` class that has nothing to do with NixOS 179 179 - to verify the context mechanics independently.See the [CI test suite](https://github.com/vic/den/tree/main/templates/ci/modules) 180 180 - for examples.

+169

docs/src/content/docs/reference/ctx.mdx

··· 1 1 + --- 2 2 + title: den.ctx Reference 3 3 + description: Context type definitions and their built-in implementations. 4 4 + --- 5 5 + 6 6 + import { Aside } from '@astrojs/starlight/components'; 7 7 + 8 8 + <Aside title="Use the Source, Luke" icon="github">[`modules/context/types.nix`](https://github.com/vic/den/blob/main/modules/context/types.nix) · [`modules/context/os.nix`](https://github.com/vic/den/blob/main/modules/context/os.nix) · [`modules/aspects/defaults.nix`](https://github.com/vic/den/blob/main/modules/aspects/defaults.nix) · Tests: [`context/`](https://github.com/vic/den/tree/main/templates/ci/modules/features/context) · [`host-propagation.nix`](https://github.com/vic/den/blob/main/templates/ci/modules/features/context/host-propagation.nix)</Aside> 9 9 + 10 10 + ## Context Type Schema 11 11 + 12 12 + Each `den.ctx.<name>` is an [aspect submodule](/explanation/aspects/) extended 13 13 + with context transformations. It inherits all options from `flake-aspects`'s 14 14 + `aspect`-type and adds `into`, and a couple of conventions: 15 15 + 16 16 + | Option | Type | Description | 17 17 + |--------|------|-------------| 18 18 + | `description` | `str` | Human-readable description | 19 19 + | `provides.${name}` | `ctx → aspect` | Self-named provider: locates the aspect for this context | 20 20 + | `provides.${target}` | `ctx → aspect` | Cross-provider: source's contribution to target contexts | 21 21 + | `into` | `attrset of (ctx → list)` | Transformations to other contexts | 22 22 + | `includes` | `list of aspect` | Parametric aspects activated for this context | 23 23 + 24 24 + Context types are also functors — callable as functions: 25 25 + 26 26 + ```nix 27 27 + aspect = den.ctx.host { host = den.hosts.x86_64-linux.igloo; }; 28 28 + ``` 29 29 + 30 30 + ## ctxApply (internal) 31 31 + 32 32 + When a context type is applied, `ctxApply` walks the full `into` graph 33 33 + and deduplicates includes using a seen-set: 34 34 + 35 35 + ```nix 36 36 + ctxApply = ctxName: _self: ctx: 37 37 + let 38 38 + pairs = collectPairs null den.ctx.${ctxName} ctx; 39 39 + in 40 40 + { includes = dedupIncludes pairs; }; 41 41 + ``` 42 42 + 43 43 + **collectPairs** recursively walks `into` transformations, producing 44 44 + `(source, ctxDef, ctx)` triples for every reachable context type. 45 45 + The `source` tracks which context type produced the transformation. 46 46 + 47 47 + **dedupIncludes** processes triples with a seen-set keyed by context name: 48 48 + 49 49 + - **First visit**: `fixedTo ctx (cleanCtx ctxDef)` — dispatches owned, static, and parametric includes — plus self-provider and cross-provider 50 50 + - **Subsequent visits**: `atLeast (cleanCtx ctxDef) ctx` — dispatches only parametric includes — plus self-provider and cross-provider 51 51 + 52 52 + For each triple, three providers are called: 53 53 + 1. **Self-provider** `ctxDef.provides.${ctxDef.name}` — the target's own aspect lookup 54 54 + 2. **Cross-provider** `source.provides.${ctxDef.name}` — the source's contribution to this target (if defined) 55 55 + 56 56 + ## Transformation Types 57 57 + 58 58 + All `into` transformations have the type `source → [ target ]`: 59 59 + 60 60 + - **Fan-out**: `{ host }: map (u: { inherit host user; }) users` — one host produces N contexts 61 61 + - **Conditional**: `{ host }: lib.optional (test host) { inherit host; }` — zero or one 62 62 + - **Pass-through**: `lib.singleton` — forward the same data as-is 63 63 + 64 64 + An empty list means the target context is not created. This enables 65 65 + conditional activation like HM detection without any explicit `if` logic 66 66 + in the pipeline. 67 67 + 68 68 + ## Contexts as Cutting-Points 69 69 + 70 70 + Context types have their own owned configs and `includes`, making them 71 71 + aspect-like cutting-points in the pipeline: 72 72 + 73 73 + ```nix 74 74 + den.ctx.hm-host.nixos.home-manager.useGlobalPkgs = true; 75 75 + den.ctx.hm-host.includes = [ 76 76 + ({ host, ... }: { nixos.home-manager.backupFileExtension = "bak"; }) 77 77 + ]; 78 78 + ``` 79 79 + 80 80 + 81 81 + ## Extending Context Flow 82 82 + 83 83 + Add transformations to existing context types from any module: 84 84 + 85 85 + ```nix 86 86 + den.ctx.hm-host.into.foo = { host }: [ { foo = host.name; } ]; 87 87 + den.ctx.foo._.foo = { foo }: { funny.names = [ foo ]; }; 88 88 + ``` 89 89 + 90 90 + The module system merges these definitions. You can also override a 91 91 + host's `mainModule` to use a completely custom context flow. 92 92 + 93 93 + ## Built-in Context Types 94 94 + 95 95 + ### den.ctx.host 96 96 + 97 97 + | Field | Value | 98 98 + |-------|-------| 99 99 + | `description` | OS | 100 100 + | `provides.host` | `{ host }:` fixedTo host aspect | 101 101 + | `provides.user` | `{ host, user }:` host's contribution to user contexts (cross-provider) | 102 102 + | `into.default` | `lib.singleton` (pass-through) | 103 103 + | `into.user` | Enumerate `host.users` | 104 104 + | `into.hm-host` | Detect HM support (from `hm-detect.nix`) | 105 105 + 106 106 + ### den.ctx.user 107 107 + 108 108 + | Field | Value | 109 109 + |-------|-------| 110 110 + | `description` | OS user | 111 111 + | `provides.user` | `{ host, user }:` fixedTo user aspect | 112 112 + | `into.default` | `lib.singleton` (pass-through) | 113 113 + 114 114 + ### den.ctx.default 115 115 + 116 116 + | Field | Value | 117 117 + |-------|-------| 118 118 + | `provides.default` | `_: { }` (empty — just a dispatcher) | 119 119 + 120 120 + Aliased as `den.default` via `lib.mkAliasOptionModule`. 121 121 + Writing `den.default.foo` is identical to `den.ctx.default.foo`. 122 122 + 123 123 + Host/user/home context types transforms into `default`, so `den.default.includes` 124 124 + functions run at each of their pipeline stages. However, owned and static configs 125 125 + are **automatically deduplicated** — only the first visit gets them. 126 126 + Parametric functions still run at every stage; use `take.exactly` to 127 127 + restrict matching if needed. 128 128 + 129 129 + ### den.ctx.home 130 130 + 131 131 + | Field | Value | 132 132 + |-------|-------| 133 133 + | `description` | Standalone Home-Manager config | 134 134 + | `provides.home` | `{ home }:` fixedTo home aspect | 135 135 + | `into.default` | `lib.singleton` | 136 136 + 137 137 + ### den.ctx.hm-host 138 138 + 139 139 + | Field | Value | 140 140 + |-------|-------| 141 141 + | `description` | Host with HM-supported OS and HM users | 142 142 + | `provides.hm-host` | `{ host }:` imports HM NixOS/Darwin module | 143 143 + | `into.hm-user` | Enumerate HM-class users | 144 144 + 145 145 + **Detection criteria** (all must be true): 146 146 + 1. Host class is `nixos` or `darwin` 147 147 + 2. At least one user has `class = "homeManager"` 148 148 + 3. `inputs.home-manager` exists, or host has a custom `hm-module` attribute 149 149 + 150 150 + If detection fails, the HM pipeline is skipped entirely. 151 151 + 152 152 + ### den.ctx.hm-user 153 153 + 154 154 + | Field | Value | 155 155 + |-------|-------| 156 156 + | `description` | Internal — forwards HM class to host | 157 157 + | `provides.hm-user` | `{ host, user }:` forward homeManager into host | 158 158 + 159 159 + ### den.ctx.hm-internal-user (internal) 160 160 + 161 161 + An internal context type used by `hm-user`. It combines: 162 162 + - The user context (`den.ctx.user { host, user }`) 163 163 + - Owned configs from the host aspect 164 164 + - Static includes from the host aspect 165 165 + - Parametric includes from the host aspect matching `{ host, user }` 166 166 + 167 167 + This ensures that when the `homeManager` class is forwarded into 168 168 + `home-manager.users.<name>`, it receives contributions from both 169 169 + the user's aspect and the host's aspect.

+24 -5

docs/src/content/docs/reference/lib.md docs/src/content/docs/reference/lib.mdx

··· 5 5 6 6 import { Aside } from '@astrojs/starlight/components'; 7 7 8 8 - <Aside type="tip">Source: [`nix/lib.nix`](https://github.com/vic/den/blob/main/nix/lib.nix) · [`nix/fn-can-take.nix`](https://github.com/vic/den/blob/main/nix/fn-can-take.nix) · [`nix/den-brackets.nix`](https://github.com/vic/den/blob/main/nix/den-brackets.nix)</Aside> 8 8 + <Aside title="Use the Source, Luke" icon="github">[`nix/lib.nix`](https://github.com/vic/den/blob/main/nix/lib.nix) · [`nix/fn-can-take.nix`](https://github.com/vic/den/blob/main/nix/fn-can-take.nix) · [`nix/den-brackets.nix`](https://github.com/vic/den/blob/main/nix/den-brackets.nix) · Tests: [`parametric.nix`](https://github.com/vic/den/blob/main/templates/ci/modules/features/parametric.nix) · [`angle-brackets.nix`](https://github.com/vic/den/blob/main/templates/ci/modules/features/angle-brackets.nix)</Aside> 9 9 10 10 ## den.lib.parametric 11 11 12 12 - Creates a parametric aspect. Alias for `parametric.withOwn parametric.atLeast`. 12 12 + Creates a parametric aspect. Alias for `(parametric.withOwn parametric.atLeast)`. 13 13 14 14 ```nix 15 15 den.lib.parametric { nixos.x = 1; includes = [ f ]; } ··· 21 21 22 22 Dispatches **only** to functions whose required args are a subset of context: 23 23 24 24 + **does include owned config, atLeast only forwards context**. 25 25 + 24 26 ```nix 25 27 F = parametric.atLeast { includes = [ a b ]; }; 26 28 ``` ··· 28 30 ### parametric.exactly 29 31 30 32 Dispatches **only** to functions whose args match context exactly: 33 33 + 34 34 + **does include owned config, atLeast only forwards context**. 31 35 32 36 ```nix 33 37 F = parametric.exactly { includes = [ a b ]; }; ··· 37 41 38 42 Replaces context with a fixed attribute set: 39 43 44 44 + Ignores any given context at call site, and replaces with a fixed one. 45 45 + Behaves like `parametric`, includes owned + static includes + function includes. 46 46 + 40 47 ```nix 41 48 F = parametric.fixedTo { x = 1; } aspect; 42 49 ``` ··· 44 51 ### parametric.expands 45 52 46 53 Merges extra attributes into received context: 54 54 + Behaves like `parametric`, includes owned + static includes + function includes. 47 55 48 56 ```nix 49 57 F = parametric.expands { extra = 1; } aspect; ··· 52 60 ### parametric.withOwn 53 61 54 62 Combinator: adds owned + statics on top of a dispatch functor: 63 63 + This is how `parametric` function itself uses `parametric.atLeast`. 55 64 56 65 ```nix 66 66 + # an exactly variant of parametric. 57 67 F = parametric.withOwn parametric.exactly aspect; 58 68 ``` 59 69 ··· 69 79 70 80 Wraps function to only be called when context has at least the required args. 71 81 82 82 + Produces an empty attrset if the context has not atLeast the expected args. 83 83 + 72 84 ### take.exactly 73 85 74 86 ```nix ··· 76 88 ``` 77 89 78 90 Only called when context has exactly these args, no more. 91 91 + 92 92 + Produces an empty attrset otherwise. 79 93 80 94 ### take.unused 81 95 ··· 89 103 90 104 Function signature introspection: 91 105 106 106 + Does not care about values, only about attribute names. 107 107 + 92 108 ```nix 93 109 den.lib.canTake { x = 1; } someFunction 94 110 # => true if someFunction can take at least { x } ··· 99 115 100 116 ## den.lib.aspects 101 117 102 102 - Re-export of `flake-aspects` library. Provides: 118 118 + Re-export of [`flake-aspects`](https://github.com/vic/flake-aspects) library. Provides: 103 119 - `aspects.types.aspectsType` — module type for aspect trees 104 120 - `aspects.types.providerType` — type for aspect providers 105 121 - `aspects.forward` — class forwarding implementation ··· 114 130 115 131 ## den.lib.owned 116 132 117 117 - Extracts only owned configs from an aspect (removes `includes`, `__functor`): 133 133 + Extracts only owned configs from an aspect (**removes** `includes`, `__functor` from someAspect): 118 134 119 135 ```nix 120 136 den.lib.owned someAspect # => { nixos = ...; darwin = ...; } ··· 124 140 125 141 Creates a functor that only resolves static includes from an aspect: 126 142 143 143 + The new aspect ignores owned configs, and functional includes that are not 144 144 + of type (ground flake-aspects): `{ class, aspect-chain }: {...}` 145 145 + 127 146 ```nix 128 128 - den.lib.statics someAspect { class = "nixos"; aspect-chain = []; } 147 147 + den.lib.statics someAspect # => <aspect with only static includes> 129 148 ``` 130 149 131 150 ## den.lib.isStatic

+1 -1

docs/src/content/docs/reference/output.md docs/src/content/docs/reference/output.mdx

··· 5 5 6 6 import { Aside } from '@astrojs/starlight/components'; 7 7 8 8 - <Aside type="tip">Source: [`modules/config.nix`](https://github.com/vic/den/blob/main/modules/config.nix) · [`modules/output.nix`](https://github.com/vic/den/blob/main/modules/output.nix)</Aside> 8 8 + <Aside title="Use the Source, Luke" icon="github">[`modules/config.nix`](https://github.com/vic/den/blob/main/modules/config.nix) · [`modules/output.nix`](https://github.com/vic/den/blob/main/modules/output.nix) · Tests: [`default-includes.nix`](https://github.com/vic/den/blob/main/templates/ci/modules/features/default-includes.nix) · [`home-manager/`](https://github.com/vic/den/tree/main/templates/ci/modules/features/home-manager)</Aside> 9 9 10 10 ## Overview 11 11

+4 -19

docs/src/content/docs/reference/schema.md docs/src/content/docs/reference/schema.mdx

··· 5 5 6 6 import { Aside } from '@astrojs/starlight/components'; 7 7 8 8 - <Aside type="tip">Source: [`modules/_types.nix`](https://github.com/vic/den/blob/main/modules/_types.nix) · [`modules/options.nix`](https://github.com/vic/den/blob/main/modules/options.nix)</Aside> 8 8 + 9 9 + <Aside title="Use the Source, Luke" icon="github">[`modules/_types.nix`](https://github.com/vic/den/blob/main/modules/_types.nix) · [`modules/options.nix`](https://github.com/vic/den/blob/main/modules/options.nix) · Tests: [`host-options.nix`](https://github.com/vic/den/blob/main/templates/ci/modules/features/host-options.nix) · [`schema-base-modules.nix`](https://github.com/vic/den/blob/main/templates/ci/modules/features/schema-base-modules.nix) · [`homes.nix`](https://github.com/vic/den/blob/main/templates/ci/modules/features/homes.nix)</Aside> 10 10 + 11 11 + `den.base` provides extensible schemas for `host`/`user`/`home`. 9 12 10 13 ## den.hosts 11 14 ··· 92 95 ``` 93 96 94 97 `den.base.conf` is automatically imported by host, user, and home. 95 95 - 96 96 - ## den.ful 97 97 - 98 98 - Namespace storage for aspect libraries: 99 99 - 100 100 - ```nix 101 101 - den.ful.<namespace>.<name> = aspect; 102 102 - ``` 103 103 - 104 104 - Populated via [`inputs.den.namespace`](/guides/namespaces/). 105 105 - 106 106 - ## flake.denful 107 107 - 108 108 - Flake output for sharing namespaces: 109 109 - 110 110 - ```nix 111 111 - flake.denful.<namespace> = den.ful.<namespace>; 112 112 - ```

+109

docs/src/content/docs/tutorials/bogus.md

··· 1 1 + --- 2 2 + title: "Template: Bug Reproduction" 3 3 + description: Create minimal reproductions for Den bug reports using nix-unit. 4 4 + --- 5 5 + 6 6 + The bogus template helps you create minimal bug reproductions. Use it when reporting issues or contributing fixes. 7 7 + 8 8 + ## Initialize 9 9 + 10 10 + ```console 11 11 + mkdir bogus && cd bogus 12 12 + nix flake init -t github:vic/den#bogus 13 13 + nix flake update den 14 14 + ``` 15 15 + 16 16 + ## Project Structure 17 17 + 18 18 + ``` 19 19 + flake.nix 20 20 + modules/ 21 21 + bug.nix # your bug reproduction 22 22 + test-base.nix # test infrastructure (DO NOT EDIT) 23 23 + ``` 24 24 + 25 25 + ## Writing a Bug Reproduction 26 26 + 27 27 + Edit `modules/bug.nix` with a minimal test case: 28 28 + 29 29 + ```nix 30 30 + { denTest, ... }: 31 31 + { 32 32 + flake.tests.bogus = { 33 33 + test-something = denTest ( 34 34 + { den, lib, igloo, tuxHm, ... }: 35 35 + { 36 36 + den.hosts.x86_64-linux.igloo.users.tux = { }; 37 37 + 38 38 + # set up the scenario 39 39 + den.aspects.igloo.nixos.something = true; 40 40 + 41 41 + # what you get 42 42 + expr = igloo.something; 43 43 + # what you expect 44 44 + expected = true; 45 45 + } 46 46 + ); 47 47 + }; 48 48 + } 49 49 + ``` 50 50 + 51 51 + ### How denTest Works 52 52 + 53 53 + `denTest` is a helper that: 54 54 + 1. Creates a fresh Den evaluation with your module 55 55 + 2. Provides helpers like `igloo` (host config), `tuxHm` (user's HM config) 56 56 + 3. Compares `expr` against `expected` using [nix-unit](https://github.com/nix-community/nix-unit) 57 57 + 58 58 + Available test helpers (from `test-base.nix`): 59 59 + 60 60 + | Helper | Description | 61 61 + |--------|-------------| 62 62 + | `igloo` | `nixosConfigurations.igloo.config` | 63 63 + | `iceberg` | `nixosConfigurations.iceberg.config` | 64 64 + | `tuxHm` | `igloo.home-manager.users.tux` | 65 65 + | `pinguHm` | `igloo.home-manager.users.pingu` | 66 66 + | `funnyNames` | Resolves an aspect for class `"funny"` and collects `.names` | 67 67 + | `show` | `builtins.trace` helper for debugging | 68 68 + 69 69 + ## Run Tests 70 70 + 71 71 + ```console 72 72 + nix flake check 73 73 + ``` 74 74 + 75 75 + ## Testing Against Different Den Versions 76 76 + 77 77 + Edit `.github/workflows/test.yml` to test against multiple Den versions: 78 78 + 79 79 + ```yaml 80 80 + strategy: 81 81 + matrix: 82 82 + rev: ["main", "v1.0.0", "abc1234"] 83 83 + ``` 84 84 + 85 85 + This helps identify regressions — include `"main"` and any release tag or commit. 86 86 + 87 87 + ## Contributing a Fix 88 88 + 89 89 + If you're submitting a fix to Den, test against your local checkout: 90 90 + 91 91 + ```console 92 92 + cd <den-working-copy> 93 93 + nix flake check --override-input den . ./templates/bogus 94 94 + ``` 95 95 + 96 96 + ## What It Provides 97 97 + 98 98 + | Feature | Provided | 99 99 + |---------|:--------:| 100 100 + | nix-unit test infrastructure | ✓ | 101 101 + | Pre-configured denTest helper | ✓ | 102 102 + | Version matrix testing | ✓ | 103 103 + | Common test helpers | ✓ | 104 104 + 105 105 + ## Next Steps 106 106 + 107 107 + - Share your reproduction repo on [GitHub Discussions](https://github.com/vic/den/discussions) 108 108 + - Read [Debug Configurations](/guides/debug/) for debugging techniques 109 109 + - See the [CI Tests template](/tutorials/ci/) for Den's own comprehensive test suite

+164

docs/src/content/docs/tutorials/ci.md

··· 1 1 + --- 2 2 + title: "Template: CI Tests" 3 3 + description: Den's own test suite — the definitive reference for every feature. 4 4 + --- 5 5 + 6 6 + The CI template is Den's comprehensive test suite. It tests every feature using [nix-unit](https://github.com/nix-community/nix-unit). This is the **best learning resource** for understanding exactly how Den behaves. 7 7 + 8 8 + ## Structure 9 9 + 10 10 + ``` 11 11 + flake.nix 12 12 + modules/ 13 13 + empty.nix # example test skeleton 14 14 + test-support/ 15 15 + eval-den.nix # denTest + evalDen helpers 16 16 + nix-unit.nix # nix-unit integration 17 17 + features/ 18 18 + angle-brackets.nix # <den/...> syntax 19 19 + conditional-config.nix # conditional imports/configs 20 20 + default-includes.nix # den.default behavior 21 21 + forward.nix # den._.forward 22 22 + homes.nix # standalone HM 23 23 + host-options.nix # host/user schema options 24 24 + namespaces.nix # namespace define/merge/export 25 25 + os-user-class.nix # user class forwarding 26 26 + parametric.nix # parametric functors 27 27 + schema-base-modules.nix # den.base modules 28 28 + special-args-custom-instantiate.nix # custom instantiation 29 29 + top-level-parametric.nix # top-level context aspects 30 30 + user-host-bidirectional-config.nix # bidirectional providers 31 31 + batteries/ 32 32 + define-user.nix # define-user battery 33 33 + flake-parts.nix # inputs' and self' 34 34 + import-tree.nix # import-tree battery 35 35 + primary-user.nix # primary-user battery 36 36 + tty-autologin.nix # tty-autologin battery 37 37 + unfree.nix # unfree packages 38 38 + user-shell.nix # user-shell battery 39 39 + context/ 40 40 + apply.nix # ctx application 41 41 + apply-non-exact.nix # non-exact matching 42 42 + cross-provider.nix # cross-provider mechanism 43 43 + custom-ctx.nix # custom context types 44 44 + den-default.nix # den.default as context 45 45 + host-propagation.nix # full host pipeline 46 46 + named-provider.nix # self-named providers 47 47 + deadbugs/ 48 48 + _external-namespace-deep-aspect.nix 49 49 + static-include-dup-package.nix 50 50 + home-manager/ 51 51 + home-managed-home.nix 52 52 + use-global-pkgs.nix 53 53 + non-dendritic/ # non-den files for import-tree tests 54 54 + provider/ # external namespace provider flake 55 55 + ``` 56 56 + 57 57 + ## Test Categories 58 58 + 59 59 + ### Core Features 60 60 + 61 61 + | Test File | What It Tests | 62 62 + |-----------|---------------| 63 63 + | [conditional-config.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/conditional-config.nix) | Conditional imports using host/user attributes | 64 64 + | [default-includes.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/default-includes.nix) | `den.default` applying to all hosts/users | 65 65 + | [host-options.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/host-options.nix) | Custom host attributes, hostName, aspect names | 66 66 + | [top-level-parametric.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/top-level-parametric.nix) | Context-aware top-level aspects | 67 67 + | [parametric.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/parametric.nix) | All parametric functors (atLeast, fixedTo, expands) | 68 68 + 69 69 + ### Bidirectional & Providers 70 70 + 71 71 + | Test File | What It Tests | 72 72 + |-----------|---------------| 73 73 + | [user-host-bidirectional-config.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/user-host-bidirectional-config.nix) | Host→user and user→host config flow | 74 74 + | [context/cross-provider.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/context/cross-provider.nix) | Source providing config to target context | 75 75 + | [context/named-provider.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/context/named-provider.nix) | Self-named provider mechanism | 76 76 + 77 77 + ### Context System 78 78 + 79 79 + | Test File | What It Tests | 80 80 + |-----------|---------------| 81 81 + | [context/apply.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/context/apply.nix) | Context application mechanics | 82 82 + | [context/apply-non-exact.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/context/apply-non-exact.nix) | Non-exact context matching | 83 83 + | [context/custom-ctx.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/context/custom-ctx.nix) | User-defined context types with `into` | 84 84 + | [context/den-default.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/context/den-default.nix) | `den.default` as a context type | 85 85 + | [context/host-propagation.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/context/host-propagation.nix) | Full host pipeline with all contributions | 86 86 + 87 87 + ### Batteries 88 88 + 89 89 + | Test File | What It Tests | 90 90 + |-----------|---------------| 91 91 + | [batteries/define-user.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/define-user.nix) | User definition across contexts | 92 92 + | [batteries/primary-user.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/primary-user.nix) | Primary user groups | 93 93 + | [batteries/user-shell.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/user-shell.nix) | Shell configuration | 94 94 + | [batteries/unfree.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/unfree.nix) | Unfree package predicates | 95 95 + | [batteries/tty-autologin.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/tty-autologin.nix) | TTY autologin service | 96 96 + | [batteries/import-tree.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/import-tree.nix) | Auto-importing class dirs | 97 97 + | [batteries/flake-parts.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/batteries/flake-parts.nix) | `inputs'` and `self'` providers | 98 98 + 99 99 + ### Advanced 100 100 + 101 101 + | Test File | What It Tests | 102 102 + |-----------|---------------| 103 103 + | [angle-brackets.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/angle-brackets.nix) | All bracket resolution paths | 104 104 + | [namespaces.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/namespaces.nix) | Local, remote, merged namespaces | 105 105 + | [forward.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/forward.nix) | Custom class forwarding | 106 106 + | [homes.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/homes.nix) | Standalone Home-Manager configs | 107 107 + | [schema-base-modules.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/schema-base-modules.nix) | `den.base.{host,user,home,conf}` | 108 108 + 109 109 + ### Bug Regressions 110 110 + 111 111 + | Test File | What It Tests | 112 112 + |-----------|---------------| 113 113 + | [deadbugs/static-include-dup-package.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/deadbugs/static-include-dup-package.nix) | Duplicate deduplication for packages/lists | 114 114 + | [deadbugs/_external-namespace-deep-aspect.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/deadbugs/_external-namespace-deep-aspect.nix) | Deep aspect access from external flakes | 115 115 + 116 116 + ### External Provider 117 117 + 118 118 + The `provider/` subdirectory is a **separate flake** that defines a namespace `provider` with aspects. It's used by the deadbugs test to verify cross-flake namespace consumption: 119 119 + 120 120 + ```nix 121 121 + # provider/modules/den.nix 122 122 + { inputs, ... }: 123 123 + { 124 124 + imports = [ inputs.den.flakeModule (inputs.den.namespace "provider" true) ]; 125 125 + provider.tools._.dev._.editors = { 126 126 + nixos.programs.vim.enable = true; 127 127 + }; 128 128 + } 129 129 + ``` 130 130 + 131 131 + ## Running CI Tests 132 132 + 133 133 + From the Den root against your local checkout: 134 134 + 135 135 + ```console 136 136 + nix flake check --override-input den . ./templates/ci 137 137 + ``` 138 138 + 139 139 + You can also run a single or a subset of tests using: 140 140 + 141 141 + ```console 142 142 + # You can use any attr-path bellow flake.tests after system-agnositc to run those specific tests: 143 143 + nix-unit --override-input den . --flake ./templates/ci#.tests.systems.x86_64-linux.system-agnostic 144 144 + ``` 145 145 + 146 146 + ## Writing New Tests 147 147 + 148 148 + Copy `modules/empty.nix` as a starting point: 149 149 + 150 150 + ```nix 151 151 + { denTest, ... }: 152 152 + { 153 153 + flake.tests.my-feature = { 154 154 + test-name = denTest ( 155 155 + { den, igloo, ... }: 156 156 + { 157 157 + den.hosts.x86_64-linux.igloo.users.tux = { }; 158 158 + expr = /* what you get */; 159 159 + expected = /* what you expect */; 160 160 + } 161 161 + ); 162 162 + }; 163 163 + } 164 164 + ```

-115

docs/src/content/docs/tutorials/context-aware.md

··· 1 1 - --- 2 2 - title: Context-Aware Configurations 3 3 - description: Make aspects produce conditional config based on host and user context. 4 4 - --- 5 5 - 6 6 - ## From Static to Dynamic 7 7 - 8 8 - So far, aspects have been static attribute sets. But Den's power comes from 9 9 - making them **functions of context**. When an aspect is a function, Den 10 10 - passes it the current context — host, user, platform — and the function 11 11 - decides what to produce. 12 12 - 13 13 - ## Step 1: A Simple Context Function 14 14 - 15 15 - Instead of a static aspect, write a function: 16 16 - 17 17 - ```nix 18 18 - { den, ... }: { 19 19 - den.aspects.igloo.includes = [ 20 20 - ({ host, ... }: { 21 21 - nixos.networking.hostName = host.name; 22 22 - }) 23 23 - ]; 24 24 - } 25 25 - ``` 26 26 - 27 27 - Den calls this function with `{ host }` containing the host's attributes. 28 28 - The result sets the hostname dynamically from the host's name. 29 29 - 30 30 - ## Step 2: React to User Context 31 31 - 32 32 - Functions receiving `{ host, user, ... }` run once per user on each host: 33 33 - 34 34 - ```nix 35 35 - { den, ... }: { 36 36 - den.default.includes = [ 37 37 - ({ host, user, ... }: { 38 38 - ${host.class}.users.users.${user.userName}.description = 39 39 - "${user.userName} on ${host.name}"; 40 40 - }) 41 41 - ]; 42 42 - } 43 43 - ``` 44 44 - 45 45 - Notice `${host.class}` — this dynamically targets `nixos` or `darwin` 46 46 - depending on the host's platform. The same function works on both. 47 47 - 48 48 - ## Step 3: Conditional Configuration 49 49 - 50 50 - Use standard Nix conditionals inside context functions: 51 51 - 52 52 - ```nix 53 53 - { den, lib, ... }: 54 54 - let 55 55 - git-for-linux = { user, host, ... }: 56 56 - if !lib.hasSuffix "darwin" host.system 57 57 - then { homeManager.programs.git.enable = true; } 58 58 - else { }; 59 59 - in { 60 60 - den.aspects.tux.includes = [ git-for-linux ]; 61 61 - } 62 62 - ``` 63 63 - 64 64 - Git is enabled only for users on Linux hosts. On Darwin, the function 65 65 - returns an empty set — no effect. 66 66 - 67 67 - ## Step 4: Use den.lib.parametric 68 68 - 69 69 - For aspects that need to forward context to their own includes, 70 70 - wrap them with `den.lib.parametric`: 71 71 - 72 72 - ```nix 73 73 - { den, ... }: 74 74 - let 75 75 - workspace = den.lib.parametric { 76 76 - nixos.networking.hostName = "from-parametric"; 77 77 - includes = [ 78 78 - ({ host, ... }: { nixos.time.timeZone = "UTC"; }) 79 79 - ]; 80 80 - }; 81 81 - in { 82 82 - den.aspects.igloo.includes = [ workspace ]; 83 83 - } 84 84 - ``` 85 85 - 86 86 - The `parametric` functor ensures that: 87 87 - 1. **Owned** config (`nixos.networking.hostName`) is always included 88 88 - 2. **Functions** in `includes` receive the forwarded context 89 89 - 3. Functions whose parameters don't match are **silently skipped** 90 90 - 91 91 - ## Step 5: Understand Matching 92 92 - 93 93 - Den matches context by **argument names**, not values: 94 94 - 95 95 - | Function signature | `{ host }` | `{ host, user }` | 96 96 - |--------------------|:---:|:---:| 97 97 - | `{ host, ... }: ...` | ✓ | ✓ | 98 98 - | `{ host, user }: ...` | ✗ | ✓ | 99 99 - | `{ never, ... }: ...` | ✗ | ✗ | 100 100 - 101 101 - - `atLeast` — function is called if context has **at least** the required args 102 102 - - `exactly` — function is called only if context has **exactly** those args 103 103 - 104 104 - ## What You've Learned 105 105 - 106 106 - - Aspects can be functions that receive `{ host, user, home, ... }` 107 107 - - Context functions produce conditional, platform-aware configurations 108 108 - - [`den.lib.parametric`](/explanation/parametric/) forwards context to nested includes 109 109 - - Unmatched functions are [silently skipped](/explanation/parametric/#matching-rules-summary) — no errors 110 110 - - `${host.class}` makes configs target the right Nix class dynamically 111 111 - 112 112 - ## Next 113 113 - 114 114 - - [Bidirectional Dependencies](/guides/bidirectional/) — hosts and users configure each other 115 115 - - [Context System](/explanation/context-system/) — deep dive into `den.ctx`

+177

docs/src/content/docs/tutorials/default.md

··· 1 1 + --- 2 2 + title: "Template: Default" 3 3 + description: Recommended starting point with flake-parts, Home-Manager, and VM testing. 4 4 + --- 5 5 + 6 6 + The default template is the recommended way to start a new Den project. It includes flake-parts, Home-Manager, dendritic flake-file, and a VM for testing. 7 7 + 8 8 + ## Initialize 9 9 + 10 10 + ```console 11 11 + mkdir my-nix && cd my-nix 12 12 + nix flake init -t github:vic/den#default 13 13 + nix flake update den 14 14 + ``` 15 15 + 16 16 + ## Project Structure 17 17 + 18 18 + ``` 19 19 + flake.nix # auto-generated by flake-file 20 20 + modules/ 21 21 + dendritic.nix # flake-file + den dendritic setup 22 22 + hosts.nix # host and user declarations 23 23 + defaults.nix # global settings (stateVersion, etc.) 24 24 + igloo.nix # host aspect 25 25 + tux.nix # user aspect 26 26 + vm.nix # VM runner 27 27 + ``` 28 28 + 29 29 + ## File by File 30 30 + 31 31 + ### hosts.nix — Declare Your Infrastructure 32 32 + 33 33 + ```nix 34 34 + { 35 35 + den.hosts.x86_64-linux.igloo.users.tux = { }; 36 36 + } 37 37 + ``` 38 38 + 39 39 + This single line declares: 40 40 + - A host `igloo` on `x86_64-linux` (class: `nixos`) 41 41 + - A user `tux` on that host (class: `homeManager`) 42 42 + 43 43 + The host and user each get an aspect (`den.aspects.igloo` and `den.aspects.tux`) that you configure in separate files. 44 44 + 45 45 + ### igloo.nix — Host Aspect 46 46 + 47 47 + ```nix 48 48 + { 49 49 + den.aspects.igloo = { 50 50 + nixos = { pkgs, ... }: { 51 51 + environment.systemPackages = [ pkgs.hello ]; 52 52 + }; 53 53 + homeManager = { pkgs, ... }: { 54 54 + home.packages = [ pkgs.vim ]; 55 55 + }; 56 56 + }; 57 57 + } 58 58 + ``` 59 59 + 60 60 + The host aspect provides: 61 61 + - **NixOS config** — system packages available to all users 62 62 + - **Home-Manager config** — default home environment for every user on this host 63 63 + 64 64 + ### tux.nix — User Aspect 65 65 + 66 66 + ```nix 67 67 + { den, ... }: 68 68 + { 69 69 + den.aspects.tux = { 70 70 + includes = [ 71 71 + den.provides.primary-user 72 72 + (den.provides.user-shell "fish") 73 73 + ]; 74 74 + homeManager = { pkgs, ... }: { 75 75 + home.packages = [ pkgs.htop ]; 76 76 + }; 77 77 + }; 78 78 + } 79 79 + ``` 80 80 + 81 81 + The user aspect: 82 82 + - Includes [`primary-user`](/reference/batteries/#primary-user) — adds wheel + networkmanager groups 83 83 + - Includes [`user-shell`](/reference/batteries/#user-shell) — sets fish as default shell at OS and HM level 84 84 + - Provides personal Home-Manager packages 85 85 + 86 86 + ### defaults.nix — Global Settings 87 87 + 88 88 + ```nix 89 89 + { 90 90 + den.default.nixos.system.stateVersion = "25.11"; 91 91 + den.default.homeManager.home.stateVersion = "25.11"; 92 92 + } 93 93 + ``` 94 94 + 95 95 + `den.default` applies settings to **all** hosts, users, and homes. This is the right place for `stateVersion` and other global policies. 96 96 + 97 97 + ### vm.nix — Test in a VM 98 98 + 99 99 + ```nix 100 100 + { inputs, den, ... }: 101 101 + { 102 102 + den.aspects.igloo.includes = [ (den.provides.tty-autologin "tux") ]; 103 103 + 104 104 + perSystem = { pkgs, ... }: { 105 105 + packages.vm = pkgs.writeShellApplication { 106 106 + name = "vm"; 107 107 + text = let 108 108 + host = inputs.self.nixosConfigurations.igloo.config; 109 109 + in '' 110 110 + ${host.system.build.vm}/bin/run-${host.networking.hostName}-vm "$@" 111 111 + ''; 112 112 + }; 113 113 + }; 114 114 + } 115 115 + ``` 116 116 + 117 117 + Run the VM with: 118 118 + 119 119 + ```console 120 120 + nix run .#vm 121 121 + ``` 122 122 + 123 123 + ### dendritic.nix — Flake Wiring 124 124 + 125 125 + ```nix 126 126 + { inputs, ... }: 127 127 + { 128 128 + imports = [ 129 129 + (inputs.flake-file.flakeModules.dendritic or { }) 130 130 + (inputs.den.flakeModules.dendritic or { }) 131 131 + ]; 132 132 + flake-file.inputs = { 133 133 + den.url = "github:vic/den"; 134 134 + flake-file.url = "github:vic/flake-file"; 135 135 + home-manager = { 136 136 + url = "github:nix-community/home-manager"; 137 137 + inputs.nixpkgs.follows = "nixpkgs"; 138 138 + }; 139 139 + }; 140 140 + } 141 141 + ``` 142 142 + 143 143 + This uses [flake-file](https://github.com/vic/flake-file) so inputs can be defined close to where they are used. Run `nix run .#write-flake` to regenerate `flake.nix` after changing inputs. 144 144 + 145 145 + ## Data Flow 146 146 + 147 147 + ```mermaid 148 148 + graph TD 149 149 + H["hosts.nix: igloo + tux"] --> CH["ctx.host {host=igloo}"] 150 150 + CH --> AI["den.aspects.igloo<br/>nixos + homeManager"] 151 151 + CH --> CU["ctx.user {host=igloo, user=tux}"] 152 152 + CU --> AT["den.aspects.tux<br/>primary-user + fish + htop"] 153 153 + CH --> HM["ctx.hm-host: import HM module"] 154 154 + HM --> HMU["ctx.hm-user: forward homeManager<br/>into home-manager.users.tux"] 155 155 + AI --> NixOS["nixosConfigurations.igloo"] 156 156 + AT --> NixOS 157 157 + HMU --> NixOS 158 158 + ``` 159 159 + 160 160 + ## What It Provides 161 161 + 162 162 + | Feature | Provided | 163 163 + |---------|:--------:| 164 164 + | NixOS host configuration | ✓ | 165 165 + | Home-Manager integration | ✓ | 166 166 + | Dendritic flake-file | ✓ | 167 167 + | VM testing | ✓ | 168 168 + | flake-parts | ✓ | 169 169 + | Darwin support | Add input | 170 170 + | Namespaces | Add manually | 171 171 + 172 172 + ## Next Steps 173 173 + 174 174 + - Edit `hosts.nix` to add more hosts or users 175 175 + - Create new aspect files under `modules/` 176 176 + - Add Darwin support by adding `nix-darwin` input 177 177 + - Explore the [Example template](/tutorials/example/) for namespaces and advanced features

+183

docs/src/content/docs/tutorials/example.md

··· 1 1 + --- 2 2 + title: "Template: Example" 3 3 + description: Feature showcase with namespaces, angle brackets, cross-platform aspects, and providers. 4 4 + --- 5 5 + 6 6 + The example template demonstrates Den's advanced features: namespaces, angle brackets, cross-platform hosts, bidirectional providers, and custom aspect libraries. 7 7 + 8 8 + ## Initialize 9 9 + 10 10 + ```console 11 11 + mkdir my-nix && cd my-nix 12 12 + nix flake init -t github:vic/den#example 13 13 + nix flake update den 14 14 + ``` 15 15 + 16 16 + ## Project Structure 17 17 + 18 18 + ``` 19 19 + flake.nix 20 20 + modules/ 21 21 + den.nix # host/home declarations 22 22 + dendritic.nix # flake-file + den wiring 23 23 + inputs.nix # flake inputs 24 24 + namespace.nix # creates the "eg" namespace 25 25 + tests.nix # CI checks 26 26 + vm.nix # VM runner 27 27 + aspects/ 28 28 + defaults.nix # global config + angle brackets demo 29 29 + alice.nix # user aspect 30 30 + igloo.nix # host aspect 31 31 + eg/ # namespace aspects 32 32 + autologin.nix 33 33 + ci-no-boot.nix 34 34 + routes.nix 35 35 + vm.nix 36 36 + vm-bootable.nix 37 37 + xfce-desktop.nix 38 38 + ``` 39 39 + 40 40 + ## Key Features Demonstrated 41 41 + 42 42 + ### Cross-Platform Hosts 43 43 + 44 44 + ```nix 45 45 + # modules/den.nix 46 46 + { 47 47 + den.hosts.x86_64-linux.igloo.users.alice = { }; 48 48 + den.hosts.aarch64-darwin.apple.users.alice = { }; 49 49 + den.homes.x86_64-linux.alice = { }; 50 50 + } 51 51 + ``` 52 52 + 53 53 + One user (`alice`) across a NixOS host, a Darwin host, and a standalone Home-Manager config. The same aspects produce appropriate configs for each platform. 54 54 + 55 55 + ### Namespaces 56 56 + 57 57 + ```nix 58 58 + # modules/namespace.nix 59 59 + { inputs, den, ... }: 60 60 + { 61 61 + imports = [ (inputs.den.namespace "eg" true) ]; 62 62 + _module.args.__findFile = den.lib.__findFile; 63 63 + } 64 64 + ``` 65 65 + 66 66 + Creates a local namespace `eg` accessible as a module argument. The `true` flag exposes it as a flake output (`flake.denful.eg`). Angle brackets are enabled via `__findFile`. 67 67 + 68 68 + ### Namespace Aspects 69 69 + 70 70 + The `eg/` directory defines reusable aspects under the `eg` namespace: 71 71 + 72 72 + ```nix 73 73 + # modules/aspects/eg/vm.nix 74 74 + { eg, ... }: 75 75 + { 76 76 + eg.vm.provides = { 77 77 + gui.includes = [ eg.vm eg.vm-bootable._.gui eg.xfce-desktop ]; 78 78 + tui.includes = [ eg.vm eg.vm-bootable._.tui ]; 79 79 + }; 80 80 + } 81 81 + ``` 82 82 + 83 83 + Aspects can have nested **provides** — `eg.vm._.gui` and `eg.vm._.tui` are sub-aspects accessed via the `_.` provider syntax. 84 84 + 85 85 + ### Angle Brackets 86 86 + 87 87 + ```nix 88 88 + # modules/aspects/defaults.nix 89 89 + { den, __findFile ? __findFile, ... }: 90 90 + { 91 91 + den.default.includes = [ 92 92 + <eg/routes> # resolves to eg.routes 93 93 + <den/define-user> # resolves to den.provides.define-user 94 94 + ]; 95 95 + } 96 96 + ``` 97 97 + 98 98 + The `<name>` syntax is shorthand for aspect lookup. `<den/define-user>` resolves to `den.provides.define-user`. See [Angle Brackets](/guides/angle-brackets/). 99 99 + 100 100 + ### Bidirectional Providers 101 101 + 102 102 + ```nix 103 103 + # modules/aspects/alice.nix — user provides config TO the host 104 104 + den.aspects.alice = { 105 105 + provides.igloo = { host, ... }: { 106 106 + nixos.programs.nh.enable = host.name == "igloo"; 107 107 + }; 108 108 + }; 109 109 + 110 110 + # modules/aspects/igloo.nix — host provides config TO the user 111 111 + den.aspects.igloo = { 112 112 + provides.alice = { user, ... }: { 113 113 + homeManager.programs.helix.enable = user.name == "alice"; 114 114 + }; 115 115 + }; 116 116 + ``` 117 117 + 118 118 + Hosts and users can contribute configuration **to each other** through `provides`. Alice enables `nh` on igloo, and igloo enables `helix` for alice. These are cross-providers activated during context transformation. 119 119 + 120 120 + ### Custom Routes 121 121 + 122 122 + ```nix 123 123 + # modules/aspects/eg/routes.nix 124 124 + { den, ... }: 125 125 + { 126 126 + eg.routes = let 127 127 + inherit (den.lib) parametric; 128 128 + mutual = from: to: den.aspects.${from.aspect}._.${to.aspect} or { }; 129 129 + routes = { host, user, ... }@ctx: 130 130 + parametric.fixedTo ctx { 131 131 + includes = [ (mutual user host) (mutual host user) ]; 132 132 + }; 133 133 + in routes; 134 134 + } 135 135 + ``` 136 136 + 137 137 + This aspect **wires bidirectional providers** between hosts and users automatically. Including `<eg/routes>` in `den.default` activates all `provides` declarations. 138 138 + 139 139 + ### Tests 140 140 + 141 141 + ```nix 142 142 + # modules/tests.nix — verifies the template works 143 143 + { 144 144 + checks."alice enabled igloo nh" = checkCond "..." igloo.programs.nh.enable; 145 145 + checks."igloo enabled alice helix" = checkCond "..." alice-at-igloo.programs.helix.enable; 146 146 + } 147 147 + ``` 148 148 + 149 149 + ## Data Flow 150 150 + 151 151 + ```mermaid 152 152 + graph TD 153 153 + D["den.nix: igloo/apple + alice"] --> CH["ctx.host"] 154 154 + CH --> AI["aspects.igloo<br/>nixos + provides.alice"] 155 155 + CH --> CU["ctx.user"] 156 156 + CU --> AA["aspects.alice<br/>includes + provides.igloo"] 157 157 + AA -->|"routes: mutual"| AI 158 158 + AI -->|"routes: mutual"| AA 159 159 + CH --> HM["ctx.hm-host"] 160 160 + AI --> NixOS["nixosConfigurations.igloo"] 161 161 + AA --> NixOS 162 162 + AI --> Darwin["darwinConfigurations.apple"] 163 163 + AA --> Darwin 164 164 + ``` 165 165 + 166 166 + ## What It Provides 167 167 + 168 168 + | Feature | Provided | 169 169 + |---------|:--------:| 170 170 + | NixOS + Darwin hosts | ✓ | 171 171 + | Home-Manager | ✓ | 172 172 + | Standalone HM config | ✓ | 173 173 + | Namespaces (`eg`) | ✓ | 174 174 + | Angle brackets | ✓ | 175 175 + | Bidirectional providers | ✓ | 176 176 + | VM testing | ✓ | 177 177 + | CI checks | ✓ | 178 178 + 179 179 + ## Next Steps 180 180 + 181 181 + - Study the `eg/` namespace aspects as examples for your own libraries 182 182 + - Read [Namespaces](/guides/namespaces/) and [Angle Brackets](/guides/angle-brackets/) 183 183 + - Explore the [CI Tests template](/tutorials/ci/) for comprehensive feature coverage

-114

docs/src/content/docs/tutorials/first-aspect.md

··· 1 1 - --- 2 2 - title: Your First Aspect 3 3 - description: Create a cross-class, reusable Nix configuration aspect. 4 4 - --- 5 5 - 6 6 - ## What is an Aspect? 7 7 - 8 8 - An aspect is a composable bundle of Nix configurations that can span multiple 9 9 - classes (NixOS, Darwin, Home-Manager). Each host, user, and home you declare 10 10 - automatically gets an aspect. 11 11 - 12 12 - ## Step 1: Declare Your Infrastructure 13 13 - 14 14 - Start with a host and user: 15 15 - 16 16 - ```nix 17 17 - # modules/hosts.nix 18 18 - { 19 19 - den.hosts.x86_64-linux.igloo.users.tux = { }; 20 20 - } 21 21 - ``` 22 22 - 23 23 - Den creates `den.aspects.igloo` (host) and `den.aspects.tux` (user) automatically. 24 24 - 25 25 - ## Step 2: Configure the Host Aspect 26 26 - 27 27 - Any module file can contribute to any aspect. Create a file for your host: 28 28 - 29 29 - ```nix 30 30 - # modules/igloo.nix 31 31 - { den, ... }: { 32 32 - den.aspects.igloo = { 33 33 - nixos.networking.hostName = "igloo"; 34 34 - nixos.time.timeZone = "UTC"; 35 35 - homeManager.programs.direnv.enable = true; 36 36 - }; 37 37 - } 38 38 - ``` 39 39 - 40 40 - The `nixos` settings apply to NixOS. The `homeManager` settings apply 41 41 - to **every user** on this host. 42 42 - 43 43 - ## Step 3: Configure the User Aspect 44 44 - 45 45 - ```nix 46 46 - # modules/vic.nix 47 47 - { den, ... }: { 48 48 - den.aspects.tux = { 49 49 - homeManager.programs.fish.enable = true; 50 50 - nixos.users.users.tux.description = "Tux the Penguin"; 51 51 - }; 52 52 - } 53 53 - ``` 54 54 - 55 55 - User aspects contribute to **every host** that has this user. 56 56 - If `tux` exists on both `igloo` and another host, both get the fish config. 57 57 - 58 58 - ## Step 4: Use Includes for Composition 59 59 - 60 60 - Aspects can include other aspects: 61 61 - 62 62 - ```nix 63 63 - # modules/gaming.nix 64 64 - { den, ... }: { 65 65 - den.aspects.gaming = { 66 66 - nixos.programs.steam.enable = true; 67 67 - homeManager.programs.mangohud.enable = true; 68 68 - }; 69 69 - 70 70 - den.aspects.igloo.includes = [ den.aspects.gaming ]; 71 71 - } 72 72 - ``` 73 73 - 74 74 - ## Step 5: Use Provides for Nesting 75 75 - 76 76 - Organize related aspects in a tree: 77 77 - 78 78 - ```nix 79 79 - { den, ... }: { 80 80 - den.aspects.tools.provides.editors = { 81 81 - homeManager.programs.vim.enable = true; 82 82 - }; 83 83 - 84 84 - den.aspects.tux.includes = [ den.aspects.tools._.editors ]; 85 85 - } 86 86 - ``` 87 87 - 88 88 - The `._. ` syntax is shorthand for `.provides.`. 89 89 - 90 90 - ## Step 6: Set Global Defaults 91 91 - 92 92 - Use `den.default` for settings shared across all hosts and users: 93 93 - 94 94 - ```nix 95 95 - # modules/defaults.nix 96 96 - { 97 97 - den.default.homeManager.home.stateVersion = "25.11"; 98 98 - den.default.nixos.system.stateVersion = "25.11"; 99 99 - } 100 100 - ``` 101 101 - 102 102 - ## What You've Learned 103 103 - 104 104 - - [Aspects](/explanation/aspects/) bundle cross-class configs (nixos, darwin, homeManager) 105 105 - - Host aspects apply to all users on that host 106 106 - - User aspects apply to all hosts with that user 107 107 - - `includes` compose aspects together 108 108 - - `provides` creates nested aspect trees 109 109 - - [`den.default`](/explanation/context-pipeline/#dendefault-is-an-alias) sets global shared values 110 110 - 111 111 - ## Next 112 112 - 113 113 - [Context-Aware Configs](/tutorials/context-aware/) — make your aspects 114 114 - respond dynamically to their host and user context.

-97

docs/src/content/docs/tutorials/getting-started.md

··· 1 1 - --- 2 2 - title: Getting Started 3 3 - description: Set up your first Den project from scratch. 4 4 - --- 5 5 - 6 6 - ## Prerequisites 7 7 - 8 8 - - [Nix](https://nixos.org/download) with flakes enabled (or use [without flakes](/guides/no-flakes/)) 9 9 - - Basic familiarity with Nix modules 10 10 - 11 11 - ## Quick Start — Launch the Demo VM 12 12 - 13 13 - Try Den instantly without installing anything: 14 14 - 15 15 - ```console 16 16 - nix run github:vic/den 17 17 - ``` 18 18 - 19 19 - ## Initialize a New Project 20 20 - 21 21 - Create a fresh Den-based flake: 22 22 - 23 23 - ```console 24 24 - mkdir my-infra && cd my-infra 25 25 - nix flake init -t github:vic/den 26 26 - nix flake update den 27 27 - ``` 28 28 - 29 29 - This creates a project with: 30 30 - 31 31 - ``` 32 32 - flake.nix # inputs and entry point 33 33 - modules/ # your Den modules go here 34 34 - hosts.nix # host and user declarations 35 35 - aspects/ # aspect definitions 36 36 - ``` 37 37 - 38 38 - ## Your flake.nix 39 39 - 40 40 - The generated `flake.nix` imports Den and uses `import-tree` to load all modules: 41 41 - 42 42 - ```nix 43 43 - { 44 44 - outputs = inputs: 45 45 - inputs.flake-parts.lib.mkFlake { inherit inputs; } 46 46 - (inputs.import-tree ./modules); 47 47 - 48 48 - inputs = { 49 49 - den.url = "github:vic/den"; 50 50 - flake-aspects.url = "github:vic/flake-aspects"; 51 51 - import-tree.url = "github:vic/import-tree"; 52 52 - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; 53 53 - flake-parts.url = "github:hercules-ci/flake-parts"; 54 54 - }; 55 55 - } 56 56 - ``` 57 57 - 58 58 - ## Declare a Host 59 59 - 60 60 - In `modules/hosts.nix`, declare your first host: 61 61 - 62 62 - ```nix 63 63 - { 64 64 - den.hosts.x86_64-linux.my-laptop.users.vic = { }; 65 65 - } 66 66 - ``` 67 67 - 68 68 - This single line creates: 69 69 - - A NixOS host named `my-laptop` on `x86_64-linux` 70 70 - - A user `vic` with Home-Manager support 71 71 - - Aspects `den.aspects.my-laptop` and `den.aspects.vic` 72 72 - 73 73 - ## Build It 74 74 - 75 75 - ```console 76 76 - nixos-rebuild switch --flake .#my-laptop 77 77 - ``` 78 78 - 79 79 - ## Available Templates 80 80 - 81 81 - | Template | Description | 82 82 - |----------|-------------| 83 83 - | `default` | Batteries-included layout | 84 84 - | `minimal` | Minimalistic Den flake | 85 85 - | `noflake` | No flakes, no flake-parts | 86 86 - | `example` | Examples and patterns | 87 87 - | `ci` | Feature test suite | 88 88 - | `bogus` | Bug reproduction | 89 89 - 90 90 - ```console 91 91 - nix flake init -t github:vic/den#minimal 92 92 - ``` 93 93 - 94 94 - ## Next Steps 95 95 - 96 96 - - [Your First Aspect](/tutorials/first-aspect/) — write cross-class configs 97 97 - - [Context-Aware Configs](/tutorials/context-aware/) — make aspects react to context

+118

docs/src/content/docs/tutorials/minimal.md

··· 1 1 + --- 2 2 + title: "Template: Minimal" 3 3 + description: The smallest possible Den setup — one host, one user, no extra dependencies. 4 4 + --- 5 5 + 6 6 + The minimal template demonstrates Den's core with zero extra dependencies beyond nixpkgs. 7 7 + 8 8 + ## Initialize 9 9 + 10 10 + ```console 11 11 + mkdir my-nix && cd my-nix 12 12 + nix flake init -t github:vic/den#minimal 13 13 + nix flake update den 14 14 + ``` 15 15 + 16 16 + ## Project Structure 17 17 + 18 18 + ``` 19 19 + flake.nix 20 20 + modules/ 21 21 + den.nix 22 22 + ``` 23 23 + 24 24 + ## flake.nix 25 25 + 26 26 + ```nix 27 27 + { 28 28 + outputs = inputs: 29 29 + (inputs.nixpkgs.lib.evalModules { 30 30 + modules = [ (inputs.import-tree ./modules) ]; 31 31 + specialArgs = { inherit inputs; }; 32 32 + }).config.flake; 33 33 + 34 34 + inputs = { 35 35 + nixpkgs.url = "https://channels.nixos.org/nixpkgs-unstable/nixexprs.tar.xz"; 36 36 + import-tree.url = "github:vic/import-tree"; 37 37 + flake-aspects.url = "github:vic/flake-aspects"; 38 38 + den.url = "github:vic/den"; 39 39 + }; 40 40 + } 41 41 + ``` 42 42 + 43 43 + Key points: 44 44 + - **No flake-parts** — uses `lib.evalModules` directly 45 45 + - **import-tree** — recursively loads all `.nix` files under `modules/` 46 46 + - **Results** land in `.config.flake` (nixosConfigurations, etc.) 47 47 + 48 48 + ## modules/den.nix 49 49 + 50 50 + ```nix 51 51 + { inputs, den, ... }: 52 52 + { 53 53 + imports = [ inputs.den.flakeModule ]; 54 54 + 55 55 + den.hosts.x86_64-linux.igloo.users.tux = { }; 56 56 + 57 57 + den.aspects.igloo = { 58 58 + nixos = { pkgs, ... }: { 59 59 + environment.systemPackages = [ pkgs.hello ]; 60 60 + boot.loader.grub.enable = false; # TODO: remove for real hardware 61 61 + fileSystems."/".device = "/dev/null"; 62 62 + }; 63 63 + }; 64 64 + 65 65 + den.aspects.tux = { 66 66 + includes = [ den.provides.primary-user ]; 67 67 + }; 68 68 + } 69 69 + ``` 70 70 + 71 71 + ### What This Declares 72 72 + 73 73 + 1. **One host** named `igloo` on `x86_64-linux` with **one user** named `tux` 74 74 + 2. **Host aspect** `den.aspects.igloo` — provides NixOS config (a package + boot/fs stubs) 75 75 + 3. **User aspect** `den.aspects.tux` — includes the [`primary-user`](/reference/batteries/#primary-user) battery 76 76 + 77 77 + ### How It Works 78 78 + 79 79 + ```mermaid 80 80 + graph TD 81 81 + H["den.hosts.x86_64-linux.igloo"] -->|"ctx.host"| A["den.aspects.igloo"] 82 82 + H -->|"ctx.user"| U["den.aspects.tux"] 83 83 + U -->|"includes"| PU["den.provides.primary-user"] 84 84 + A -->|"resolve nixos"| NixOS["nixosConfigurations.igloo"] 85 85 + ``` 86 86 + 87 87 + 1. Den reads `den.hosts` and creates a `ctx.host { host = igloo }` context 88 88 + 2. The host aspect `igloo` is activated with its NixOS config 89 89 + 3. For each user, a `ctx.user { host, user }` context is created 90 90 + 4. The user aspect `tux` includes `primary-user` (adds wheel/networkmanager groups) 91 91 + 5. Everything resolves into `nixosConfigurations.igloo` 92 92 + 93 93 + ## Build It 94 94 + 95 95 + ```console 96 96 + nix build .#nixosConfigurations.igloo.config.system.build.toplevel 97 97 + ``` 98 98 + 99 99 + ## Customize 100 100 + 101 101 + To add your own host configuration, edit `den.aspects.igloo.nixos`. To add user packages, add a `homeManager` key to `den.aspects.tux` (requires adding `home-manager` input). Or keep it simple — the minimal template works without Home-Manager. 102 102 + 103 103 + ## What It Provides 104 104 + 105 105 + | Feature | Provided | 106 106 + |---------|:--------:| 107 107 + | NixOS host configuration | ✓ | 108 108 + | User with wheel/networkmanager | ✓ | 109 109 + | Home-Manager | ✗ | 110 110 + | Darwin support | ✗ | 111 111 + | Namespaces | ✗ | 112 112 + | VM testing | ✗ | 113 113 + 114 114 + ## Next Steps 115 115 + 116 116 + - Add more aspects in separate files under `modules/` 117 117 + - Graduate to the [Default template](/tutorials/default/) for Home-Manager support 118 118 + - Read [Core Principles](/explanation/core-principles/) to understand the context pipeline

+130

docs/src/content/docs/tutorials/noflake.md

··· 1 1 + --- 2 2 + title: "Template: No-Flake" 3 3 + description: Using Den with stable Nix — no flakes needed. 4 4 + --- 5 5 + 6 6 + The noflake template shows that Den works perfectly without Nix flakes. It uses [npins](https://github.com/andir/npins) for dependency management and works with stable Nix. 7 7 + 8 8 + ## Initialize 9 9 + 10 10 + Since this template doesn't use flakes, clone it manually: 11 11 + 12 12 + ```console 13 13 + mkdir my-nix && cd my-nix 14 14 + cp -r $(nix eval --raw 'github:vic/den#templates.noflake.path')/* . 15 15 + npins update den 16 16 + ``` 17 17 + 18 18 + Or use `nix flake init` if you have flakes enabled: 19 19 + 20 20 + ```console 21 21 + nix flake init -t github:vic/den#noflake 22 22 + ``` 23 23 + 24 24 + ## Project Structure 25 25 + 26 26 + ``` 27 27 + default.nix # entry point (replaces flake.nix) 28 28 + with-inputs.nix # input resolver (replaces flake.lock) 29 29 + npins/ 30 30 + default.nix # npins fetcher 31 31 + sources.json # pinned dependencies 32 32 + modules/ 33 33 + den.nix # host/user declarations + aspects 34 34 + ``` 35 35 + 36 36 + ## File by File 37 37 + 38 38 + ### default.nix — Entry Point 39 39 + 40 40 + ```nix 41 41 + let 42 42 + outputs = inputs: 43 43 + (inputs.nixpkgs.lib.evalModules { 44 44 + modules = [ (inputs.import-tree ./modules) ]; 45 45 + specialArgs = { 46 46 + inherit inputs; 47 47 + inherit (inputs) self; 48 48 + }; 49 49 + }).config; 50 50 + in 51 51 + import ./with-inputs.nix outputs 52 52 + ``` 53 53 + 54 54 + This is the noflake equivalent of `flake.nix`. It uses `lib.evalModules` directly — the same mechanism Den uses internally. 55 55 + 56 56 + ### with-inputs.nix — Input Resolution 57 57 + 58 58 + This file resolves npins sources into a flake-compatible `inputs` attrset. It reads `flake.nix` from each dependency to discover transitive inputs and wires them together. 59 59 + 60 60 + ### modules/den.nix — Configuration 61 61 + 62 62 + ```nix 63 63 + { inputs, ... }: 64 64 + { 65 65 + imports = [ inputs.den.flakeModule ]; 66 66 + 67 67 + den.default.nixos = { 68 68 + fileSystems."/".device = "/dev/fake"; 69 69 + boot.loader.grub.enable = false; 70 70 + }; 71 71 + 72 72 + den.hosts.x86_64-linux.igloo.users.tux = { }; 73 73 + 74 74 + den.aspects.igloo = { 75 75 + nixos = { pkgs, ... }: { 76 76 + environment.systemPackages = [ pkgs.vim ]; 77 77 + }; 78 78 + }; 79 79 + 80 80 + den.aspects.tux = { 81 81 + nixos = { 82 82 + imports = [ inputs.nix-maid.nixosModules.default ]; 83 83 + users.users.tux = { 84 84 + isNormalUser = true; 85 85 + maid.file.home.".gitconfig".text = '' 86 86 + [user] 87 87 + name=Tux 88 88 + ''; 89 89 + }; 90 90 + }; 91 91 + }; 92 92 + } 93 93 + ``` 94 94 + 95 95 + Notable differences from the flake templates: 96 96 + - Uses [nix-maid](https://github.com/vic/nix-maid) instead of Home-Manager (lighter alternative) 97 97 + - User config is done directly in `nixos` class (no HM class needed) 98 98 + 99 99 + ## Build 100 100 + 101 101 + ```console 102 102 + npins update den 103 103 + nixos-rebuild build --file . -A flake.nixosConfigurations.igloo 104 104 + ``` 105 105 + 106 106 + Or with `nix-build`: 107 107 + 108 108 + ```console 109 109 + nix-build -A flake.nixosConfigurations.igloo.config.system.build.toplevel 110 110 + ``` 111 111 + 112 112 + :::note 113 113 + Den places configurations under the `flake` attribute following the flake outputs schema, even without flakes. This is the default top-level attribute for Den output. 114 114 + ::: 115 115 + 116 116 + ## What It Provides 117 117 + 118 118 + | Feature | Provided | 119 119 + |---------|:--------:| 120 120 + | NixOS host configuration | ✓ | 121 121 + | No flakes required | ✓ | 122 122 + | npins dependency pinning | ✓ | 123 123 + | nix-maid (HM alternative) | ✓ | 124 124 + | Home-Manager | ✗ (use nix-maid) | 125 125 + | flake-parts | ✗ | 126 126 + 127 127 + ## Next Steps 128 128 + 129 129 + - Read [Use Without Flakes](/guides/no-flakes/) for more details on flake-free usage 130 130 + - Consider the [Minimal template](/tutorials/minimal/) if you want flakes but not flake-parts

+61

docs/src/content/docs/tutorials/overview.md

··· 1 1 + --- 2 2 + title: Templates Overview 3 3 + description: All available Den templates and when to use each one. 4 4 + --- 5 5 + 6 6 + Den ships six templates that cover progressively complex setups. Use `nix flake init` to scaffold a new project: 7 7 + 8 8 + ```console 9 9 + nix flake init -t github:vic/den#<template> 10 10 + ``` 11 11 + 12 12 + ## Choosing a Template 13 13 + 14 14 + | Template | Use case | Flakes | flake-parts | Home-Manager | 15 15 + |----------|----------|:------:|:-----------:|:------------:| 16 16 + | [**minimal**](/tutorials/minimal/) | Smallest possible Den setup | ✓ | ✗ | ✗ | 17 17 + | [**default**](/tutorials/default/) | Recommended starting point | ✓ | ✓ | ✓ | 18 18 + | [**example**](/tutorials/example/) | Feature showcase with namespaces | ✓ | ✓ | ✓ | 19 19 + | [**noflake**](/tutorials/noflake/) | Stable Nix, no flakes | ✗ | ✗ | ✗ | 20 20 + | [**bogus**](/tutorials/bogus/) | Bug reproduction | ✓ | ✓ | ✓ | 21 21 + | [**ci**](/tutorials/ci/) | Den's own test suite | ✓ | ✓ | ✓ | 22 22 + 23 23 + ## Quick Start 24 24 + 25 25 + ```console 26 26 + mkdir my-nix && cd my-nix 27 27 + nix flake init -t github:vic/den 28 28 + nix flake update den 29 29 + ``` 30 30 + 31 31 + This clones the **default** template. Edit `modules/hosts.nix` to declare your machines, then: 32 32 + 33 33 + ```console 34 34 + nix run .#vm 35 35 + ``` 36 36 + 37 37 + ## Project Structure 38 38 + 39 39 + Every template follows the same pattern: 40 40 + 41 41 + ``` 42 42 + flake.nix # or default.nix for noflake 43 43 + modules/ 44 44 + den.nix # host/user declarations + den.flakeModule import 45 45 + *.nix # aspect definitions, one concern per file 46 46 + ``` 47 47 + 48 48 + Den uses [import-tree](https://github.com/vic/import-tree) to recursively load all `.nix` files under `modules/`. You never need to manually list imports — just create files. 49 49 + 50 50 + ## What Each Template Demonstrates 51 51 + 52 52 + - **minimal** — The absolute minimum: one host, one user, no extra dependencies 53 53 + - **default** — Production-ready structure with Home-Manager, VM testing, dendritic flake-file 54 54 + - **example** — Namespaces, angle brackets, cross-platform (NixOS + Darwin), providers 55 55 + - **noflake** — Using Den with npins instead of flakes 56 56 + - **bogus** — Creating minimal reproductions for bug reports with nix-unit 57 57 + - **ci** — Comprehensive tests covering every Den feature (your best learning resource) 58 58 + 59 59 + ## Next Steps 60 60 + 61 61 + Start with the [Minimal template](/tutorials/minimal/) to understand Den's core, then graduate to [Default](/tutorials/default/) for a real setup.

+1 -1

modules/aspects/defaults.nix

··· 4 4 { 5 5 imports = [ (lib.mkAliasOptionModule [ "default" ] [ "ctx" "default" ]) ]; 6 6 7 7 - ctx.default.conf = _: { }; 7 7 + ctx.default._.default = _: { }; 8 8 9 9 }; 10 10 }

+5 -5

modules/aspects/provides/home-manager/hm-integration.nix

··· 43 43 { 44 44 den.provides.home-manager = { }; 45 45 46 46 - den.ctx.home.desc = "Standalone Home-Manager config provided by home aspect"; 47 47 - den.ctx.home.conf = { home }: parametric.fixedTo { inherit home; } den.aspects.${home.aspect}; 46 46 + den.ctx.home.description = "Standalone Home-Manager config provided by home aspect"; 47 47 + den.ctx.home._.home = { home }: parametric.fixedTo { inherit home; } den.aspects.${home.aspect}; 48 48 den.ctx.home.into.default = lib.singleton; 49 49 50 50 den.ctx.hm-host.into.hm-user = intoHmUsers; 51 51 - den.ctx.hm-user.desc = "(internal)"; 52 52 - den.ctx.hm-user.conf = forwardedToHost; 51 51 + den.ctx.hm-user.description = "(internal)"; 52 52 + den.ctx.hm-user._.hm-user = forwardedToHost; 53 53 54 54 - den.ctx.hm-internal-user.conf = 54 54 + den.ctx.hm-internal-user._.hm-internal-user = 55 55 { host, user }: 56 56 { class, aspect-chain }: 57 57 {

+2 -2

modules/aspects/provides/home-manager/hm-os.nix

··· 43 43 { 44 44 den.ctx.host.into.hm-host = hm-detect; 45 45 46 46 - den.ctx.hm-host.desc = description; 47 47 - den.ctx.hm-host.conf = 46 46 + den.ctx.hm-host.description = description; 47 47 + den.ctx.hm-host._.hm-host = 48 48 { host }: 49 49 { 50 50 ${host.class}.imports = [ (hm-module host) ];

+10 -13

modules/context/os.nix

··· 2 2 let 3 3 inherit (den.lib.parametric) fixedTo atLeast; 4 4 5 5 - ctx.host.desc = "OS"; 6 6 - ctx.host.conf = { host }: fixedTo { inherit host; } den.aspects.${host.aspect}; 5 5 + ctx.host.description = "OS"; 6 6 + ctx.host._.host = { host }: fixedTo { inherit host; } den.aspects.${host.aspect}; 7 7 + ctx.host._.user = 8 8 + { host, user }@ctx: 9 9 + { 10 10 + includes = [ (atLeast den.aspects.${host.aspect} ctx) ]; 11 11 + }; 7 12 8 13 ctx.host.into.default = lib.singleton; 9 14 ctx.host.into.user = { host }: map (user: { inherit host user; }) (lib.attrValues host.users); 10 15 11 11 - ctx.user.desc = "OS user"; 12 12 - ctx.user.conf = 16 16 + ctx.user.description = "OS user"; 17 17 + ctx.user._.user = 13 18 { host, user }@ctx: 14 19 { 15 15 - includes = 16 16 - let 17 17 - hostAspect = den.aspects.${host.aspect}; 18 18 - userAspect = den.aspects.${user.aspect}; 19 19 - in 20 20 - [ 21 21 - (fixedTo ctx userAspect) 22 22 - (atLeast hostAspect ctx) 23 23 - ]; 20 20 + includes = [ (fixedTo ctx den.aspects.${user.aspect}) ]; 24 21 }; 25 22 26 23 ctx.user.into.default = lib.singleton;

+38 -47

modules/context/types.nix

··· 1 1 { den, lib, ... }: 2 2 let 3 3 inherit (den.lib) parametric; 4 4 - inherit (den.lib.aspects.types) providerType; 4 4 + inherit (den.lib.aspects.types) aspectSubmodule providerType; 5 5 6 6 ctxType = lib.types.submodule ( 7 7 - { name, ... }: 7 7 + { name, config, ... }: 8 8 { 9 9 - freeformType = lib.types.lazyAttrsOf lib.types.deferredModule; 10 10 - options = { 11 11 - name = lib.mkOption { 12 12 - description = "Context type name"; 13 13 - type = lib.types.str; 14 14 - default = name; 15 15 - }; 16 16 - desc = lib.mkOption { 17 17 - description = "Context description"; 18 18 - type = lib.types.str; 19 19 - default = ""; 20 20 - }; 21 21 - conf = lib.mkOption { 22 22 - description = "Obtain a configuration aspect for context"; 23 23 - type = lib.types.functionTo providerType; 24 24 - default = { }; 25 25 - }; 26 26 - into = lib.mkOption { 27 27 - description = "Context transformations"; 28 28 - type = lib.types.lazyAttrsOf (lib.types.functionTo (lib.types.listOf lib.types.raw)); 29 29 - default = { }; 30 30 - }; 31 31 - includes = lib.mkOption { 32 32 - description = "Parametric aspects to include for this context"; 33 33 - type = lib.types.listOf providerType; 34 34 - default = [ ]; 35 35 - }; 36 36 - __functor = lib.mkOption { 37 37 - description = "Apply context with dedup across into targets."; 38 38 - type = lib.types.functionTo (lib.types.functionTo providerType); 39 39 - readOnly = true; 40 40 - internal = true; 41 41 - visible = false; 42 42 - default = ctxApply; 43 43 - }; 9 9 + imports = aspectSubmodule.getSubModules; 10 10 + options.into = lib.mkOption { 11 11 + description = "Context transformations to other context types"; 12 12 + type = lib.types.lazyAttrsOf (lib.types.functionTo (lib.types.listOf lib.types.raw)); 13 13 + default = { }; 44 14 }; 15 15 + config.__functor = lib.mkForce (ctxApply config.name); 45 16 } 46 17 ); 47 18 48 19 cleanCtx = 49 49 - ctx: 50 50 - builtins.removeAttrs ctx [ 20 20 + self: 21 21 + builtins.removeAttrs self [ 51 22 "name" 52 52 - "desc" 53 53 - "conf" 23 23 + "description" 54 24 "into" 25 25 + "provides" 55 26 "__functor" 27 27 + "modules" 28 28 + "resolve" 29 29 + "_module" 30 30 + "_" 56 31 ]; 57 32 58 33 collectPairs = 59 59 - self: ctx: 34 34 + source: self: ctx: 60 35 [ 61 36 { 62 62 - inherit ctx; 37 37 + inherit ctx source; 63 38 ctxDef = self; 64 39 } 65 40 ] 66 41 ++ lib.concatLists ( 67 67 - lib.mapAttrsToList (n: into: lib.concatMap (v: collectPairs den.ctx.${n} v) (into ctx)) self.into 42 42 + lib.mapAttrsToList ( 43 43 + n: into: lib.concatMap (v: collectPairs self den.ctx.${n} v) (into ctx) 44 44 + ) self.into 68 45 ); 69 46 70 47 dedupIncludes = 71 48 let 49 49 + crossProvider = 50 50 + p: 51 51 + let 52 52 + src = p.source; 53 53 + n = p.ctxDef.name; 54 54 + in 55 55 + if src == null then (_: { }) else src.provides.${n} or (_: { }); 56 56 + 72 57 go = 73 58 acc: remaining: 74 59 if remaining == [ ] then ··· 80 65 n = p.ctxDef.name; 81 66 clean = cleanCtx p.ctxDef; 82 67 isFirst = !(acc.seen ? ${n}); 68 68 + selfProvider = p.ctxDef.provides.${n} or (_: { }); 69 69 + cross = crossProvider p; 83 70 items = 84 71 if isFirst then 85 72 [ 86 73 (parametric.fixedTo p.ctx clean) 87 87 - (p.ctxDef.conf p.ctx) 74 74 + (selfProvider p.ctx) 75 75 + (cross p.ctx) 88 76 ] 89 77 else 90 78 [ 91 79 (parametric.atLeast clean p.ctx) 92 92 - (p.ctxDef.conf p.ctx) 80 80 + (selfProvider p.ctx) 81 81 + (cross p.ctx) 93 82 ]; 94 83 in 95 84 go { ··· 105 94 result = [ ]; 106 95 } pairs; 107 96 108 108 - ctxApply = self: ctx: { includes = dedupIncludes (collectPairs self ctx); }; 97 97 + ctxApply = ctxName: _self: ctx: { 98 98 + includes = dedupIncludes (collectPairs null den.ctx.${ctxName} ctx); 99 99 + }; 109 100 110 101 in 111 102 {

+4 -4

templates/ci/modules/features/context/apply-non-exact.nix

··· 3 3 flake.tests.ctx-non-exact.test-apply-non-exact-less = denTest ( 4 4 { den, funnyNames, ... }: 5 5 { 6 6 - den.ctx.foobar.desc = "{foo,bar} context"; 7 7 - den.ctx.foobar.conf = 6 6 + den.ctx.foobar.description = "{foo,bar} context"; 7 7 + den.ctx.foobar._.foobar = 8 8 # use atLeast if you get error: function called with unexpected argument 9 9 den.lib.take.atLeast ( 10 10 { foo, bar }: ··· 30 30 flake.tests.ctx-non-exact.test-apply-non-exact-more = denTest ( 31 31 { den, funnyNames, ... }: 32 32 { 33 33 - den.ctx.foobar.desc = "{foo,bar} context"; 34 34 - den.ctx.foobar.conf = 33 33 + den.ctx.foobar.description = "{foo,bar} context"; 34 34 + den.ctx.foobar._.foobar = 35 35 # use exactly if you want to restrict to not having more args 36 36 den.lib.take.exactly ( 37 37 { foo, bar }:

+2 -2

templates/ci/modules/features/context/apply.nix

··· 3 3 flake.tests.ctx.test-apply = denTest ( 4 4 { den, funnyNames, ... }: 5 5 { 6 6 - den.ctx.foobar.desc = "{foo,bar} context"; 7 7 - den.ctx.foobar.conf = 6 6 + den.ctx.foobar.description = "{foo,bar} context"; 7 7 + den.ctx.foobar._.foobar = 8 8 { foo, bar }: 9 9 { 10 10 funny.names = [

+128

templates/ci/modules/features/context/cross-provider.nix

··· 1 1 + { denTest, ... }: 2 2 + { 3 3 + flake.tests.ctx-cross-provider = { 4 4 + 5 5 + test-source-provides-target = denTest ( 6 6 + { 7 7 + den, 8 8 + lib, 9 9 + funnyNames, 10 10 + ... 11 11 + }: 12 12 + { 13 13 + den.ctx.parent.description = "{x} context"; 14 14 + den.ctx.parent._.parent = 15 15 + { x }: 16 16 + { 17 17 + funny.names = [ "parent-${x}" ]; 18 18 + }; 19 19 + den.ctx.parent._.child = 20 20 + { x, y }: 21 21 + { 22 22 + funny.names = [ "parent-for-child-${x}-${y}" ]; 23 23 + }; 24 24 + den.ctx.parent.into.child = 25 25 + { x }: 26 26 + [ 27 27 + { 28 28 + inherit x; 29 29 + y = "derived"; 30 30 + } 31 31 + ]; 32 32 + 33 33 + den.ctx.child._.child = 34 34 + { x, y }: 35 35 + { 36 36 + funny.names = [ "child-${y}" ]; 37 37 + }; 38 38 + 39 39 + expr = funnyNames (den.ctx.parent { x = "hello"; }); 40 40 + expected = [ 41 41 + "child-derived" 42 42 + "parent-for-child-hello-derived" 43 43 + "parent-hello" 44 44 + ]; 45 45 + } 46 46 + ); 47 47 + 48 48 + test-source-provider-per-target-value = denTest ( 49 49 + { 50 50 + den, 51 51 + lib, 52 52 + funnyNames, 53 53 + ... 54 54 + }: 55 55 + { 56 56 + den.ctx.src.description = "source"; 57 57 + den.ctx.src._.src = 58 58 + { x }: 59 59 + { 60 60 + funny.names = [ x ]; 61 61 + }; 62 62 + den.ctx.src._.dst = 63 63 + { x, i }: 64 64 + { 65 65 + funny.names = [ "src-for-${x}-${toString i}" ]; 66 66 + }; 67 67 + den.ctx.src.into.dst = 68 68 + { x }: 69 69 + [ 70 70 + { 71 71 + inherit x; 72 72 + i = 1; 73 73 + } 74 74 + { 75 75 + inherit x; 76 76 + i = 2; 77 77 + } 78 78 + ]; 79 79 + 80 80 + den.ctx.dst._.dst = 81 81 + { x, i }: 82 82 + { 83 83 + funny.names = [ "dst-${toString i}" ]; 84 84 + }; 85 85 + 86 86 + expr = funnyNames (den.ctx.src { x = "a"; }); 87 87 + expected = [ 88 88 + "a" 89 89 + "dst-1" 90 90 + "dst-2" 91 91 + "src-for-a-1" 92 92 + "src-for-a-2" 93 93 + ]; 94 94 + } 95 95 + ); 96 96 + 97 97 + test-no-cross-provider-when-absent = denTest ( 98 98 + { 99 99 + den, 100 100 + lib, 101 101 + funnyNames, 102 102 + ... 103 103 + }: 104 104 + { 105 105 + den.ctx.src.description = "source without cross-provider"; 106 106 + den.ctx.src._.src = 107 107 + { x }: 108 108 + { 109 109 + funny.names = [ x ]; 110 110 + }; 111 111 + den.ctx.src.into.dst = { x }: [ { y = x; } ]; 112 112 + 113 113 + den.ctx.dst._.dst = 114 114 + { y }: 115 115 + { 116 116 + funny.names = [ "dst-${y}" ]; 117 117 + }; 118 118 + 119 119 + expr = funnyNames (den.ctx.src { x = "val"; }); 120 120 + expected = [ 121 121 + "dst-val" 122 122 + "val" 123 123 + ]; 124 124 + } 125 125 + ); 126 126 + 127 127 + }; 128 128 + }

+7 -7

templates/ci/modules/features/context/custom-ctx.nix

··· 10 10 ... 11 11 }: 12 12 { 13 13 - den.ctx.greeting.desc = "{hello} context"; 14 14 - den.ctx.greeting.conf = 13 13 + den.ctx.greeting.description = "{hello} context"; 14 14 + den.ctx.greeting._.greeting = 15 15 { hello }: 16 16 { 17 17 funny.names = [ hello ]; 18 18 }; 19 19 den.ctx.greeting.into.shout = { hello }: [ { shout = lib.toUpper hello; } ]; 20 20 21 21 - den.ctx.shout.conf = 21 21 + den.ctx.shout._.shout = 22 22 { shout }: 23 23 { 24 24 funny.names = [ shout ]; ··· 35 35 test-ctx-includes-static-and-parametric = denTest ( 36 36 { den, funnyNames, ... }: 37 37 { 38 38 - den.ctx.foo.desc = "{foo} context"; 39 39 - den.ctx.foo.conf = 38 38 + den.ctx.foo.description = "{foo} context"; 39 39 + den.ctx.foo._.foo = 40 40 { foo }: 41 41 { 42 42 funny.names = [ foo ]; ··· 63 63 test-ctx-owned = denTest ( 64 64 { den, funnyNames, ... }: 65 65 { 66 66 - den.ctx.bar.desc = "{x} context"; 67 67 - den.ctx.bar.conf = 66 66 + den.ctx.bar.description = "{x} context"; 67 67 + den.ctx.bar._.bar = 68 68 { x }: 69 69 { 70 70 funny.names = [ x ];

+70

templates/ci/modules/features/context/named-provider.nix

··· 1 1 + { denTest, ... }: 2 2 + { 3 3 + flake.tests.ctx-named-provider = { 4 4 + 5 5 + test-self-named-provider = denTest ( 6 6 + { den, funnyNames, ... }: 7 7 + { 8 8 + den.ctx.greet.description = "{who} context"; 9 9 + den.ctx.greet._.greet = 10 10 + { who }: 11 11 + { 12 12 + funny.names = [ "hello-${who}" ]; 13 13 + }; 14 14 + 15 15 + expr = funnyNames (den.ctx.greet { who = "nix"; }); 16 16 + expected = [ "hello-nix" ]; 17 17 + } 18 18 + ); 19 19 + 20 20 + test-self-named-plus-owned = denTest ( 21 21 + { den, funnyNames, ... }: 22 22 + { 23 23 + den.ctx.greet.description = "{who} context"; 24 24 + den.ctx.greet._.greet = 25 25 + { who }: 26 26 + { 27 27 + funny.names = [ "hello-${who}" ]; 28 28 + }; 29 29 + den.ctx.greet.funny.names = [ "owned" ]; 30 30 + 31 31 + expr = funnyNames (den.ctx.greet { who = "nix"; }); 32 32 + expected = [ 33 33 + "hello-nix" 34 34 + "owned" 35 35 + ]; 36 36 + } 37 37 + ); 38 38 + 39 39 + test-named-provider-with-into = denTest ( 40 40 + { 41 41 + den, 42 42 + lib, 43 43 + funnyNames, 44 44 + ... 45 45 + }: 46 46 + { 47 47 + den.ctx.greet.description = "{who} context"; 48 48 + den.ctx.greet._.greet = 49 49 + { who }: 50 50 + { 51 51 + funny.names = [ who ]; 52 52 + }; 53 53 + den.ctx.greet.into.yell = { who }: [ { shout = lib.toUpper who; } ]; 54 54 + 55 55 + den.ctx.yell._.yell = 56 56 + { shout }: 57 57 + { 58 58 + funny.names = [ shout ]; 59 59 + }; 60 60 + 61 61 + expr = funnyNames (den.ctx.greet { who = "world"; }); 62 62 + expected = [ 63 63 + "WORLD" 64 64 + "world" 65 65 + ]; 66 66 + } 67 67 + ); 68 68 + 69 69 + }; 70 70 + }