Modular, context-aware and aspect-oriented dendritic Nix configurations.
Discussions: https://oeiuwq.zulipchat.com/join/nqp26cd4kngon6mo3ncgnuap/
den.oeiuwq.com
configurations
den
dendritic
nix
aspect
oriented
remove bidirectional from agent md
+20
-159
+19
-159
AGENTS_EXAMPLE.md
+19
-159
AGENTS_EXAMPLE.md
···
294
294
295
295
---
296
296
297
-
## 5. Bidirectional Configuration (Critical Advanced Feature)
298
-
299
-
Den supports two patterns for Host↔User bidirectional configuration.
300
-
Read `https://den.oeiuwq.com/guides/bidirectional` and apply these rules:
301
-
302
-
### 5.1 Built-in Bidirectionality (`den._.bidirectional`)
303
-
304
-
This makes a HOST contribute configuration TO its users' home environments.
305
-
Enable per-user or globally:
306
-
307
-
```nix
308
-
# Only for specific user
309
-
den.aspects.alice.includes = [ den._.bidirectional ];
310
-
311
-
# For ALL users (recommended for host-provides-home-env patterns)
312
-
den.ctx.user.includes = [ den._.bidirectional ];
313
-
```
314
-
315
-
**How it works:** When bidirectionality is enabled, the user pipeline calls
316
-
`igloo.includes` TWICE: once with `{host}` (for host-only config) and once
317
-
with `{host, user}` (so the host can contribute to THIS specific user's home).
318
-
319
-
**Mandatory: use take guards** in `igloo.includes` to handle dual invocation:
320
-
321
-
```nix
322
-
# In igloo.includes — only runs for host-level context
323
-
(den.lib.take.exactly ({ host }: { nixos.networking.hostName = host.hostName; }))
297
+
## 5. Mutual Host<->User Configuration
324
298
325
-
# In igloo.includes — only runs when user is present (host→user home contribution)
326
-
(den.lib.take.atLeast ({ host, user }: { homeManager.programs.vim.enable = true; }))
327
-
```
328
-
329
-
This pattern is ideal when: a host wants to provide a common home environment
330
-
to ALL of its users (e.g., all users on `igloo` get `vim` configured in their home).
299
+
Den supports a patterns for Host↔User mutual configuration.
300
+
Read `https://den.oeiuwq.com/guides/mutual` and apply these rules:
331
301
332
-
### 5.2 Explicit Mutual Provider (`den._.mutual-provider`)
302
+
### 5.1 Explicit Mutual Provider (`den._.mutual-provider`)
333
303
334
-
For EXPLICIT named host↔user pairings. More verbose, more precise:
304
+
For EXPLICIT named host↔user pairings.
335
305
336
306
```nix
337
307
# Enable for everything
···
346
316
den.aspects.tux.provides.igloo = { host, ... }: {
347
317
nixos.programs.nh.enable = true;
348
318
};
349
-
```
350
319
351
-
### 5.3 When to Use Which
320
+
# Host provides to all users
321
+
den.aspects.igloo.provides.to-users = {};
352
322
353
-
| Pattern | Use when |
354
-
|---------|----------|
355
-
| Built-in bidirectionality | Host provides common env to ALL its users |
356
-
| `mutual-provider` | Explicit, named host↔user pair configurations |
357
-
| User `nixos` class | User always contributes to any host it's on |
358
-
| Host `homeManager` class | Host always contributes to all user homes |
323
+
# User provides to all hosts
324
+
den.aspects.tux.provides.to-hosts = {};
325
+
```
359
326
360
327
---
361
328
···
393
360
- `unfree [...]` — `nixpkgs.config.allowUnfreePredicate` for named packages
394
361
- `tty-autologin "user"` — `services.getty.autologinUser`
395
362
- `mutual-provider` — explicit named host↔user cross-config
396
-
- `bidirectional` — host contributes to user homes in pipeline
397
363
- `forward` — creates custom Nix classes (see §7)
398
364
- `import-tree` — auto-imports legacy non-dendritic `.nix` directories
399
365
- `inputs'` — flake-parts system-qualified inputs
···
519
485
};
520
486
```
521
487
522
-
### 8.3 Host contributing home config to users (bidirectional)
488
+
### 8.3 Host contributing home config to users
523
489
524
490
```nix
525
491
# Host igloo provides vim to ALL its users' home environments
526
-
den.aspects.igloo = {
492
+
den.aspects.igloo.provides.to-users = {
527
493
homeManager.programs.vim.enable = true; # goes to ALL users on igloo
528
494
};
529
-
den.ctx.user.includes = [ den._.bidirectional ];
495
+
den.ctx.user.includes = [ den._.mutual-provider ];
530
496
```
531
497
532
498
### 8.4 Multiple home environments per user
···
711
677
- [ ] `den.schema.*` defines shared options instead of repeating per-host
712
678
- [ ] `den.default` sets `stateVersion` for all classes
713
679
- [ ] All batteries used instead of manual equivalents
714
-
- [ ] `bidirectional` or `mutual-provider` used for host↔user cross-config
715
-
- [ ] `take.exactly`/`take.atLeast` guards on bidirectional aspects
680
+
- [ ] `mutual-provider` used for host↔user cross-config
681
+
- [ ] `perHost`/`perUser`/`take.exactly`/`take.atLeast` guards on mutual aspects
716
682
- [ ] One file per concern in `modules/aspects/`
717
683
- [ ] Non host/user specific re-usable aspects in `modules/community/<namespace>/`
718
684
- [ ] No monolithic `configuration.nix` style files
···
729
695
730
696
All source truth lives at:
731
697
- `https://den.oeiuwq.com` — official documentation
732
-
- `https://den.oeiuwq.com/guides/bidirectional` — bidirectional guide, Bidirectionality is an advanced feature not recommended.
698
+
- `https://den.oeiuwq.com/guides/mutual` — Mutual Host<->User config
733
699
- `https://github.com/vic/den/tree/main/templates/ci/modules/features/` — executable feature tests (best learning resource)
734
700
- `https://github.com/vic/den/tree/main/modules/aspects/provides/` — all batteries source
735
701
- `https://github.com/vic/flake-aspects` — underlying aspect library
···
772
738
Adding bluetooth to a new host is one line: include the aspect.
773
739
Removing it is deleting that line.
774
740
775
-
```
776
-
777
-
**File:** docs/src/content/docs/guides/bidirectional.mdx (L60-153)
778
-
```text
779
-
## What Bidirectionality means
780
-
781
-
__Bidirectionality__ means that not only a User contributes
782
-
configuration to a Host, but **also** that a Host contributes
783
-
configurations to a User.
784
-
785
-
This is useful when the Host wishes to provide a
786
-
commmon home environment for its users.
787
-
788
-
## `den.provides.bidirectional`
789
-
790
-
Bidirectionality is enabled __per-user__ or for _all_ of them.
791
-
792
-
```nix
793
-
# only tux takes configurations from its hosts
794
-
den.aspects.tux.includes = [ den._.bidirectional ];
795
-
796
-
# for ALL users
797
-
den.ctx.user.includes = [ den._.bidirectional ];
798
-
```
799
-
800
-
When Bidirectionality is enabled, the interaction looks like this:
801
-
802
-
```mermaid
803
-
sequenceDiagram
804
-
participant Den
805
-
participant host as den.ctx.host
806
-
participant user as den.ctx.user
807
-
participant igloo as den.aspects.igloo
808
-
participant tux as den.aspects.tux
809
-
810
-
Den ->> host : {host = igloo}
811
-
812
-
host ->> igloo : request nixos class
813
-
igloo -->> igloo : each igloo.includes takes { host }
814
-
igloo -->> host : { nixos = ... } owned and parametric results
815
-
816
-
host ->> user : fan-outs for each user: { host, user }
817
-
818
-
user ->> tux : request nixos class
819
-
820
-
tux ->> igloo : request home class
821
-
igloo -->> igloo : each igloo.includes takes { host, user }
822
-
igloo -->> tux : { hjem = ... } owned and parametric results
823
-
824
-
tux -->> tux : home classes forwarded as nixos class
825
-
826
-
tux -->> tux : each tux.includes takes { host, user }
827
-
tux -->> user : { nixos = ... } owned and parametric results
828
-
829
-
user -->> host : { nixos = ... } all user contributions
830
-
831
-
host -->> Den : complete nixos module for lib.nixosSystem
832
-
833
-
```
834
-
835
-
Crucial points here are `igloo.includes takes { host }` and `igloo.includes takes { host, user }`.
836
-
837
-
Because the list of aspects at `igloo.includes` get invoked twice, with different contexts,
838
-
functions at `igloo.includes` must take care of the following:
839
-
840
-
```nix
841
-
# use den.lib.take.exactly to avoid being called with `{host, user}`
842
-
take.exactly ({ host }: ...)
843
-
844
-
# use den.lib.take.atLeast to avoid being called with `{host}`
845
-
take.atLeast ({ host, user }: ...)
846
-
```
847
-
848
-
Read the documentation at [`context/user.nix`](https://github.com/vic/den/blob/main/modules/context/user.nix) for all the details.
849
-
850
-
## `den.provides.mutual-provider`
851
-
852
-
An alternative to bidirectionality is [`den.provides.mutual-provider`](https://github.com/vic/den/blob/main/modules/aspects/provides/mutual-provider.nix).
853
-
854
-
This battery is more explicit, since it requires an explicit `.provides.` relationship between users and hosts.
855
-
856
-
```nix
857
-
# Host provides to a particular user
858
-
den.aspects.igloo.provides.tux = {
859
-
hjem = ...;
860
-
};
861
-
862
-
# User provides to a particular host
863
-
den.aspects.tux.provides.igloo = {
864
-
nixos = ...;
865
-
};
866
-
```
867
-
868
-
To enable it for both users and hosts, include at default:
869
-
870
-
```nix
871
-
den.default.includes = [ den._.mutual-provider ];
872
-
```
873
-
```
874
-
875
741
**File:** docs/src/content/docs/guides/configure-aspects.mdx (L127-187)
876
-
```text
877
742
878
743
1. Static (plain attribute set): `{ nixos.foo = ...; }`
879
744
2. Static (flake-aspects' leaf): `{class, aspect-chain}: { ${class}.foo = ...; }`
···
1032
897
den.default.includes = [ den._.mutual-provider ];
1033
898
```
1034
899
1035
-
This is not the same as the built-in bidirectionality:
1036
-
1037
900
```nix
1038
901
# contributes to ALL users of this host
1039
-
den.aspects.my-host.homeManager = { ... }
902
+
den.aspects.my-host.provides.to-users.homeManager = { ... }
1040
903
1041
904
# contributes to ALL hosts of where my-user exist
1042
905
den.aspects.my-user.nixos = { ... }
1043
906
```
1044
-
1045
-
The difference is that this allows you to wire bidirectionality between
1046
-
explictly-named hosts/users pairs.
1047
907
1048
908
A user providing config TO the host:
1049
909
···
2355
2215
schema-base-modules.nix # den.schema modules
2356
2216
special-args-custom-instantiate.nix # custom instantiation
2357
2217
top-level-parametric.nix # top-level context aspects
2358
-
user-host-bidirectional-config.nix # bidirectional providers
2218
+
user-host-mutual-config.nix # mutual providers
2359
2219
batteries/
2360
2220
define-user.nix # define-user battery
2361
2221
flake-parts.nix # inputs' and self'
···
2398
2258
2399
2259
| Test File | What It Tests |
2400
2260
|-----------|---------------|
2401
-
| [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 |
2261
+
| [user-host-mutual-config.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/user-host-mutual-config.nix) | Host→user and user→host config flow |
2402
2262
| [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 |
2403
2263
| [context/named-provider.nix](https://github.com/vic/den/blob/main/templates/ci/modules/features/context/named-provider.nix) | Self-named provider mechanism |
2404
2264