mstream · mstream · Jan 8, 2025 · Jan 9, 2025 · Jan 9, 2025 · Jan 21, 2025
diff --git a/.editorconfig b/.editorconfig
diff --git a/.envrc b/.envrc
@@ -1 +1,3 @@
+strict_env
+watch_file partitions/development/**/*
 use flake
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
@@ -10,19 +10,21 @@ jobs:
   linting-and-testing:
     runs-on: ubuntu-24.04
     steps:
-      - name: Check out the repo
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
       - name: Set up Nix
         uses: cachix/install-nix-action@v30
         with:
           extra_nix_config: |
             access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
             substituters = https://cache.nixos.org/
-          nix_path: nixpkgs=channel:nixos-24.11
+          nix_path: nixpkgs=channel:nixos-
+      - name: Check out the repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up direnv
+        uses: HatsuneMiku3939/direnv-action@v1
       - name: Run tests and linters
-        run: nix develop --command just validate-project
+        run: nix develop --command just --list && nix develop --command just validate-project
       - name: Generate documentation markdown documents
         run: nix develop --command just generate-documentation
       - name: Check if all generated files have been already commited

diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
 __pycache__
 .psc-ide-port
+**/flake.backup.nix
 just-flake.just
 mermaid-filter.err
 node_modules

diff --git a/docs/README.md b/docs/README.md
@@ -4,9 +4,9 @@
 
 ______________________________________________________________________
 
-![nix-chad logo](nix-chad.png)
+![nix-chad logo](./assets/nix-chad.png)
 
-An opinionated MacOS setup focused on software development.
+An opinionated macOS setup focused on software development.
 
 ## Features
 
@@ -21,30 +21,30 @@ appears.
 
 #### programming/configuration languages support
 
-![nvim dhall example screenshot](nvim-dhall-example.png)
-
-| language   | actions | completion | diagnostics | formatting | highlighting |
-| :--------- | :-----: | :--------: | :---------: | :--------: | :----------: |
-| bash       |    ☒    |     ☑      |      ☑      |     ☑      |      ☑       |
-| dhall      |    ☒    |     ☑      |      ☑      |     ☑      |      ☑       |
-| docker     |    ☒    |     ☒      |      ☑      |     ☒      |      ☑       |
-| GitHub Actions workflow |    ☑    |     ☑       |      ☑      |     ☑      |      ☑       |
-| html       |    ☒    |     ☑      |      ☑      |     ☑      |      ☑       |
-| java       |    ☒    |     ☑      |      ☑      |     ☑      |      ☑       |
-| json       |    ☒    |     ☑      |      ☑      |     ☑      |      ☑       |
-| javascript |    ☑    |     ☑      |      ☑      |     ☑      |      ☑       |
-| lua        |    ☑    |     ☑      |      ☑      |     ☑      |      ☑       |
-| markdown   |    ☑    |     ☑      |      ☑      |     ☑      |      ☑       |
-| nix        |    ☒    |     ☑      |      ☑      |     ☑      |      ☑       |
-| purescript |    ☑    |     ☑      |      ☑      |     ☑      |      ☑       |
-| python     |    ☑    |     ☑      |      ☑      |     ☑      |      ☑       |
-| typescript |    ☑    |     ☑      |      ☑      |     ☑      |      ☑       |
-| yaml       |    ☑    |     ☒      |      ☑      |     ☑      |      ☑       |
+![nvim dhall example screenshot](./assets/nvim-dhall-example.png)
+
+| language                | actions | completion | diagnostics | formatting | highlighting |
+| :---------------------- | :-----: | :--------: | :---------: | :--------: | :----------: |
+| bash                    | ☒       | ☑          | ☑           | ☑          | ☑            |
+| dhall                   | ☒       | ☑          | ☑           | ☑          | ☑            |
+| docker                  | ☒       | ☒          | ☑           | ☒          | ☑            |
+| GitHub Actions workflow | ☑       | ☑          | ☑           | ☑          | ☑            |
+| html                    | ☒       | ☑          | ☑           | ☑          | ☑            |
+| java                    | ☒       | ☑          | ☑           | ☑          | ☑            |
+| json                    | ☒       | ☑          | ☑           | ☑          | ☑            |
+| javascript              | ☑       | ☑          | ☑           | ☑          | ☑            |
+| lua                     | ☑       | ☑          | ☑           | ☑          | ☑            |
+| markdown                | ☑       | ☑          | ☑           | ☑          | ☑            |
+| nix                     | ☒       | ☑          | ☑           | ☑          | ☑            |
+| purescript              | ☑       | ☑          | ☑           | ☑          | ☑            |
+| python                  | ☑       | ☑          | ☑           | ☑          | ☑            |
+| typescript              | ☑       | ☑          | ☑           | ☑          | ☑            |
+| yaml                    | ☑       | ☒          | ☑           | ☑          | ☑            |
 
 #### discoverable key mappings
 
 After pressing `\` key a window enumerating all key mappings appears.
-The same windows shows when user starts but does not finish a key
+The same window shows when user starts but does not finish a key
 sequence which has some action assigned to it.
 
 ## Prerequisites
@@ -63,7 +63,7 @@ nix flake init --template github:mstream/nix-chad/main#default
 
 ### Tweaking
 
-Update any config entries to your liking like in
+Update any config entries to your liking, like in
 [this](https://github.com/mstream/nix-chad/blob/main/examples/custom/flake.nix) example.
 
 ### Applying
@@ -75,9 +75,37 @@ After any change to configuration, run from the directory where
 nix run .#switch
 ```
 
+#### Warning
+
+While it is easy to roll back unwanted/broken configuration by either
+reverting your configuration changes or using a different `nix-chad`
+flake revision, there are some classes of misconfigurations that are
+more difficult to undo.
+
+One of them is one that results in an error during ZSH shell
+initialization. If that results in, e.g. `PATH` environmental variable
+not being properly set, you may lose easy access to your binaries.
+
+In this situation, to recover back to working state, you may need to:
+- switch to Bash using an absolute binary path
+- use GUI tools (maybe enough to edit but not enough to rebuild Nix
+  configuration)
+- set `PATH` environmental variable manually (requires knowledge about
+  Nix)
+- install needed binaries without nix (an overkill just for recovery)
+- using absolute `nix store` paths (very fiddly)
+
+None of these options are convenient and most of them require
+relatively broad administrative knowledge. Thus, **after every switch,
+it is highly recommended to:**
+- leave current shell session open
+- create a new one,
+- observe if initialization scripts do not produce any errors,
+- and if so, use the previous session to fix the issues
+
 ## Updating
 
-To stay up to date witch changes to Nix Chad, run periodically:
+To stay up-to-date witch changes to Nix Chad, run periodically:
 
 ```bash
 nix flake update

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -7,13 +7,17 @@
 # Reference Guide
 
 - [Options](options.generated.md)
-
 - [Key Mappings](keymaps.generated.md)
-
 - [For Developers](for-developers/README.md)
-
-  - [Library](for-developers/library.generated.md)
-
-______________________________________________________________________
-
-[Contributors](contributors.md)
+  - [Chad Library](for-developers/chad-library/README.md)
+    - [attribute sets (attrsets)](for-developers/chad-library/attrsets.md)
+    - [bash code generation helpers (bash)](for-developers/chad-library/bash.md)
+    - [various constants (constants)](for-developers/chad-library/constants.md)
+    - [enumerations (enum)](for-developers/chad-library/enum.md)
+    - [functions (functions)](for-developers/chad-library/functions.md)
+    - [lists manipulation (lists)](for-developers/chad-library/lists.md)
+    - [lua code generation helpers (lua)](for-developers/chad-library/lua.md)
+    - [markdown code generation helpers (markdown)](for-developers/chad-library/markdown.md)
+    - [nix CLI bash command generation helpers (nixCli)](for-developers/chad-library/nix-cli.md)
+    - [macOS keyboard shortcuts configuration support (shortcuts)](for-developers/chad-library/shortcuts.md)
+    - [strings manipulation (strings)](for-developers/chad-library/strings.md)
diff --git a/docs/nix-chad.png → docs/assets/nix-chad.png b/docs/nix-chad.png → docs/assets/nix-chad.png
diff --git a/docs/nvim-dhall-example.png → docs/assets/nvim-dhall-example.png b/docs/nvim-dhall-example.png → docs/assets/nvim-dhall-example.png
diff --git a/docs/for-developers/README.md b/docs/for-developers/README.md
@@ -1,3 +1,30 @@
 # For Developers
 
-Bla bla bla
+## Flake inputs
+
+### Choosing version
+
+Since this project uses flake-parts partitions module, flake inputs
+are stored separately per each partition. This introduces possibility
+of using different versions of inputs when evaluating different 
+flake output attributes. This is possible even when inputs share a 
+reference to the same branch. This is because commit revision is being
+resolved and stored in the repo at the time of running `nix flake lock`
+command, and this may happen at different times. In order to guarantee
+that they share the same versions, use these rules: 
+
+1. If the input repository uses tags - use them.
+1. If the input repository does not use tags - use commit hashes.
+1. For `nixpkgs` use commit hashes from the branch which is appropriate for this project, namely `nixpkgs-{NIXOS_RELEASE_VERSION}-darwin`.
+1. For `home-manager` use commit hashes from the branch which corresponds to the `nixpkgs` version, namely `release-${NIXOS_RELEASE_VERSION}`.
+1. For `nix-darwin` use commit hashes from the branch which corresponds to the `nixpkgs` version, namely `nix-darwin-${NIXOS_RELEASE_VERSION}`.
+1. For `nixvim` use commit hashes from the branch which corresponds to the `nixpkgs` version, namely `nixos-${NIXOS_RELEASE_VERSION}`.
+
+### Control version of transitive dependencies
+
+For each input of a flake type, identify its dependencies, define them
+as this project's inputs and make them being used by the input with the
+help of `inputs.{NAME_OF_TRANSITIVE_INPUT}.follows` property.
+
+
+
diff --git a/docs/for-developers/chad-library/README.md b/docs/for-developers/chad-library/README.md
@@ -0,0 +1,24 @@
+# Chad Library
+
+- [attrsets](./attrsets.md)
+
+- [bash](./bash.md)
+
+- [constants](./constants.md)
+
+- [enum](./enum.md)
+
+- [functions](./functions.md)
+
+- [lists](./lists.md)
+
+- [lua](./lua.md)
+
+- [markdown](./markdown.md)
+
+- [nixCli](./nix-cli.md)
+
+- [shortcuts](./shortcuts.md)
+
+- [strings](./strings.md)
+
diff --git a/docs/for-developers/chad-library/attrsets.md b/docs/for-developers/chad-library/attrsets.md
@@ -0,0 +1,56 @@
+# attribute sets {#sec-functions-library-attrsets}
+
+
+## `lib.attrsets.generate` {#function-library-lib.attrsets.generate}
+
+Generate an attribute set from a list of values
+
+### Example
+
+```nix
+generate ["a" "b" "c"] (v: {"${v}1"=v;"${v}2"=v;})
+=>
+{a1="a";a2="a";b1="b";b2="b";c1="c";c2="c";}
+```
+
+### Type
+
+```
+generate :: [Any] -> (Any -> AttrSet) -> AttrSet
+```
+
+### Arguments
+
+values
+: List of values
+
+generator
+: A function transforming a single value into an attribute set
+
+## `lib.attrsets.merge` {#function-library-lib.attrsets.merge}
+
+Deep merge two attribute sets
+
+### Example
+
+```nix
+merge {a="a";c={c1="c1";}} {b="b";c={c2="c2";}}
+=>
+{a="a";b="b";c={c1="c1";c2="c2";}}
+```
+
+### Type
+
+```
+merge :: AttrSet -> AttrSet -> AttrSet
+```
+
+### Arguments
+
+left
+: Left attribute set
+
+right
+: Right attribute set
+
+