deploy: 1d129b2

ARCHITECTURE.html

@@ -181,11 +181,11 @@ <h1 id="standard-design-and-architecture"><a class="header" href="#standard-desi
 <p>If the topics discussed herein are dear to you, please take it as an invitation to get involved.</p>
 <p>This design document shall be stable and amendments go through a proper process of consideration.</p>
 <h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
-<p>Standard is a collection of functionality and best practices (<em>&quot;framework&quot;</em>) to bootstrap and sustain the automatable sections of the Software Development Lifecycle (SDLC) <em>efficiently</em> with the power of Nix and Flakes.
+<p>Standard is a collection of functionality and best practices (<em>"framework"</em>) to bootstrap and sustain the automatable sections of the Software Development Lifecycle (SDLC) <em>efficiently</em> with the power of Nix and Flakes.
 In particular, Standard is a <em>Horizontal* Integration Framework</em> which integrates <em>vertical*</em> tooling.</p>
 <blockquote>
 <p><sub>We occasionally adapt concepts from non-technical contexts. This is one instance.</sub></p>
-<p><em>Vertical Tooling</em> does one thing and does it well in a narrow scope (i.e &quot;vertical&quot;).</p>
+<p><em>Vertical Tooling</em> does one thing and does it well in a narrow scope (i.e "vertical").</p>
 <p><em>Horizontal Tooling</em> stitches vertical tooling together to a polished whole.</p>
 </blockquote>
 <p>What is being integrated are the end-to-end automatable sections of the SDLC.
@@ -224,7 +224,7 @@ <h2 id="ideals"><a class="header" href="#ideals">Ideals</a></h2>
 <ul>
 <li><em>Use nix only where it is best suited</em> — a Nix maximalist approach may be an innate condition to some of us, but to build bridges we deeply recognize and value other perspectives and don't dismiss them as ignorance.</li>
 <li><em>Disrupt where disruption is necessary</em> — the Nix ecosystem has a fairly rigid set of principles and norms that we don't think always apply in every use case.</li>
-<li><em>Look left, right, above and beyond</em> — our end-to-end perspective commands us to actively seek and reach out to other projects and ecosystems to compose our value chain; there's no place for the &quot;not invented here&quot;-syndrome.</li>
+<li><em>Look left, right, above and beyond</em> — our end-to-end perspective commands us to actively seek and reach out to other projects and ecosystems to compose our value chain; there's no place for the "not invented here"-syndrome.</li>
 </ul>
 <h2 id="scope"><a class="header" href="#scope">Scope</a></h2>
 <p>These are big goals and ideals.
@@ -268,7 +268,7 @@ <h3 id="standards-components-and-their-value-contribution"><a class="header" hre
 <p>What is Standard made of? And how do its components contribute value?</p>
 <p>On the left side of the graphic, we show how Standard, like an onion, is build in layers:</p>
 <p>Center to Standard is <a href="https://github.com/paisano-tui/core"><code>divnix/paisano</code></a>.
-This flake (i.e. &quot;Nix library&quot;) implements two main abstractions: Block Types and Cells.</p>
+This flake (i.e. "Nix library") implements two main abstractions: Block Types and Cells.</p>
 <p><em><strong>Block Types</strong></em> are not unlike Rust's traits or Golang's interfaces.
 They are abstract definitions of artifact classes.
 Those abstract classes implement <em>shared functionality</em>.</p>
@@ -296,13 +296,13 @@ <h3 id="paisano-code-organization"><a class="header" href="#paisano-code-organiz
 When configuring Standard, she names her Blocks using Standard's Block Types so that Paisano's importer can pick them up, too.
 By doing that, she also declares the repository's artifact type system to humans and machines.</p>
 <p>Machines can make great use of that to interact with the artifact type system in multiple ways.
-Paisano exports structured json-serializable data about a repository's <em>typed</em> artifacts in its so-called &quot;Paisano Registry&quot;.
+Paisano exports structured json-serializable data about a repository's <em>typed</em> artifacts in its so-called "Paisano Registry".
 A CLI or TUI, as is bundled with Standard, or even a web user interface can consume, represent and act upon that data.</p>
 <p>And so can CI.</p>
 <p>In fact, this is an innovation in the SDLC space:
 We can devise an implementation of a CI which, by querying Paisano's Registry, autonomously discovers all work that needs to be done.
 In order to demonstrate the value of this proposition, we made a reference implementation for GitHub Actions over at <a href="https://github.com/divnix/std-action"><code>divnix/std-action</code></a>.
-To our knowledge, this is the first and only &quot;zero config&quot; CI implementation based on the principles of artifact typing and code organization.
+To our knowledge, this is the first and only "zero config" CI implementation based on the principles of artifact typing and code organization.
 By using these principles rather than a rigid opinionated structure, it also remains highly flexible and adapts well to the user's preferences &amp; needs.</p>
 <p>In summary, all these organization and typing principles enable:</p>
 <ul>
@@ -325,7 +325,7 @@ <h3 id="standards-block-types-devops-type-system"><a class="header" href="#stand
 <p>As mentioned above, Standard exploits the Block Type abstraction to provide artifact types for the SDLC.
 Within the semantics of each Block Type, we implement shared functionality.
 This is designed to offer the user an optimized, audited implementation.
-Alleviates the burden of devising &quot;yet another&quot; local implementation of otherwise well-understood generic functionality, such as, the building of a package or the pushing of a container image.</p>
+Alleviates the burden of devising "yet another" local implementation of otherwise well-understood generic functionality, such as, the building of a package or the pushing of a container image.</p>
 <h3 id="standards-cells-function-library"><a class="header" href="#standards-cells-function-library">Standard's Cells (Function Library)</a></h3>
 <p>Alongside the <strong>Packaging Pipeline</strong>, Standard provides a curated assortment of library functions and integrations that users can adopt.
 While optional, an audited and community maintained function library and its corresponding documentation fulfills the promise of productivity, shared mental models and ease of adoption.</p>

COMPARE.html

@@ -205,9 +205,9 @@ <h3 id="flake-parts"><a class="header" href="#flake-parts">flake-parts</a></h3>
       /* snip */
     }
     {
-      devShells = std.harvest self [&quot;automation&quot; &quot;shells&quot;];
-      packages = std.harvest self [[&quot;std&quot; &quot;cli&quot;] [&quot;std&quot; &quot;packages&quot;]];
-      templates = std.pick self [&quot;presets&quot; &quot;templates&quot;];
+      devShells = std.harvest self ["automation" "shells"];
+      packages = std.harvest self [["std" "cli"] ["std" "packages"]];
+      templates = std.pick self ["presets" "templates"];
     };
 }
 </code></pre>

PITCH.html

@@ -188,9 +188,9 @@ <h1 id="value-matrix"><a class="header" href="#value-matrix">Value Matrix</a></h
 <p>It is essential to have an understanding of what they value, so let's try to get an overview.
 We'll make use of a high level value matrix with simple sentiment scores:</p>
 <ul>
-<li>😍 → <i>&quot;absolutely love it!!!&quot;</i></li>
-<li>😄 → <i>&quot;feels pretty good.&quot;</i></li>
-<li>😐 → <i>&quot;whatever?!?&quot;</i></li>
+<li>😍 → <i>"absolutely love it!!!"</i></li>
+<li>😄 → <i>"feels pretty good."</i></li>
+<li>😐 → <i>"whatever?!?"</i></li>
 </ul>
 <div class="table-wrapper"><table><thead><tr><th></th><th style="text-align: center">Software Sponsor [Principal]</th><th style="text-align: center">Provider of SDLC Automation [Agent]</th><th style="text-align: center">Consumer of SDLC Automation [Agent]</th></tr></thead><tbody>
 <tr><td>Productivity</td><td style="text-align: center">😍</td><td style="text-align: center">😍</td><td style="text-align: center">😄</td></tr>

explain/architecture-decision-records/index.html

@@ -192,9 +192,9 @@ <h2 id="context"><a class="header" href="#context">Context</a></h2>
 <!-- write an answer to this question below -->
 <p>Repository navigation is among the first activities to build a mental model of any given repository.
 The Nix Ecosystem has come up with some weak conventions: these are variations that are mainly informed by the <code>nixpkgs</code> repository, itself.
-Despite that, users find it difficult to quickly &quot;wrap their head&quot; around a new project.
+Despite that, users find it difficult to quickly "wrap their head" around a new project.
 This is often times a result of an organically grown file organization that has trouble keeping up with growing project semantics.
-As a result, onboading onto a &quot;new&quot; nix project even within the same organizational context, sometimes can be a very frustrating and time-consuming activity.</p>
+As a result, onboading onto a "new" nix project even within the same organizational context, sometimes can be a very frustrating and time-consuming activity.</p>
 <h2 id="decision"><a class="header" href="#decision">Decision</a></h2>
 <blockquote>
 <p>What is the change that we're proposing and/or doing?</p>
@@ -206,9 +206,9 @@ <h2 id="decision"><a class="header" href="#decision">Decision</a></h2>
 <p>Hence, 3 levels of organization are adopted.
 These levels correspond to the abstract organizational concepts of:</p>
 <ul>
-<li>consistent collection of functionality (&quot;what makes sense to group together?&quot;)</li>
-<li>repository output type (&quot;what types of gitops artifacts are produced?&quot;)</li>
-<li>named outputs (&quot;what are the actual outputs?&quot;)</li>
+<li>consistent collection of functionality ("what makes sense to group together?")</li>
+<li>repository output type ("what types of gitops artifacts are produced?")</li>
+<li>named outputs ("what are the actual outputs?")</li>
 </ul>
 <h2 id="consequences"><a class="header" href="#consequences">Consequences</a></h2>
 <blockquote>
@@ -219,7 +219,7 @@ <h2 id="consequences"><a class="header" href="#consequences">Consequences</a></h
 <p>That same prototypical mental model also speeds up scaffolding of new content and code.</p>
 <p>At the expense of nested folders, it may still be further expanded, if additional organization is required.
 All the while that the primary meta-information about a project is properly communicated through these first three levels via the file system api, itself (think <code>ls</code> / <code>rg</code> / <code>fd</code>).</p>
-<p>On the other hand, this rigidity is sometimes overkill and users may resort to filler names such as &quot;<code>default</code>&quot;, because a given semantic only produces singletons.
+<p>On the other hand, this rigidity is sometimes overkill and users may resort to filler names such as "<code>default</code>", because a given semantic only produces singletons.
 This is acceptable, however, because this parallellity in addressing even these singleton values trades for very easy expansion or refactoring, as the meta-models of code organization already align.</p>
 <hr />
 <h1 id="2-restrict-the-calling-interface"><a class="header" href="#2-restrict-the-calling-interface">2. Restrict the calling interface</a></h1>
@@ -235,7 +235,7 @@ <h2 id="context-1"><a class="header" href="#context-1">Context</a></h2>
 Over time, the <code>callPackage</code> idiom was developed that destructures arbitrary attributes of an 80k <em>upstream</em> attributeset provided by <code>nixpkgs</code>.
 A complicating side condition is added, where overlays modify that original upstream packages set in arbitrary ways.
 This is not a problem for people, who know nixpkgs by heart and it is not a problem for the author either.
-It is a problem for the future code reader, Nix expert or less so, who needs to grasp the essence of &quot;what's going on&quot; under a productivity side condition.</p>
+It is a problem for the future code reader, Nix expert or less so, who needs to grasp the essence of "what's going on" under a productivity side condition.</p>
 <p>Local reasoning is a tried and tested strategy to help mitigate those issues.</p>
 <p>In a variant of this problem, we observe only somewhat convergent, but still largely diverging styles of passing arguments in general across the repository context.</p>
 <h2 id="decision-1"><a class="header" href="#decision-1">Decision</a></h2>
@@ -246,13 +246,13 @@ <h2 id="decision-1"><a class="header" href="#decision-1">Decision</a></h2>
 <p>Encourage local reasoning by always fully qualifing identifiers within the scope of a single file.</p>
 <p>In order to do so, the entry level nix files of this framework have exactly one possible interface: <code>{inputs, cell}</code>.</p>
 <p><code>inputs</code> represent the global inputs, whereas <code>cell</code> keeps reference to the local context.
-<em>A Cell is the first ordering priciple for &quot;consistent collection of functionality&quot;.</em></p>
+<em>A Cell is the first ordering priciple for "consistent collection of functionality".</em></p>
 <h2 id="consequences-1"><a class="header" href="#consequences-1">Consequences</a></h2>
 <blockquote>
 <p>What becomes easier or more difficult to do because of this change?</p>
 </blockquote>
 <!-- write an answer to this question below -->
-<p>This restricts up to the prescribed 3 layers of organization the notion of &quot;how files can communicate with each other&quot;.</p>
+<p>This restricts up to the prescribed 3 layers of organization the notion of "how files can communicate with each other".</p>
 <p>That inter-files-interface is the <em>only</em> global context to really grasp, and it is structurally aligned across all Standard projects.</p>
 <p>By virtue of this meta model of a global context and inter-file-communications, for a somewhat familiarized code reader the barriers to local reasoning are greatly reduced.</p>
 <p>The two context references are well known (flake inputs &amp; cell-local blocks) and easily discoverable.</p>
@@ -277,20 +277,20 @@ <h2 id="decision-2"><a class="header" href="#decision-2">Decision</a></h2>
 <p>What is the change that we're proposing and/or doing?</p>
 </blockquote>
 <!-- write an answer to this question below -->
-<p>De-systemize everything to the &quot;current&quot; system and effectively hiding the explict manipulation from plain sight in most cases.</p>
+<p>De-systemize everything to the "current" system and effectively hiding the explict manipulation from plain sight in most cases.</p>
 <p>An attribute set, that differentiates for systems on any given level of its tree, is <code>deSystemized</code>.</p>
-<p>This means that all child attributes of the &quot;current&quot; system are lifted onto the &quot;system&quot;-level as siblings to the system attributes.</p>
+<p>This means that all child attributes of the "current" system are lifted onto the "system"-level as siblings to the system attributes.</p>
 <p>That also means, if explicit reference to <code>system</code> is necessary, it is still there among the siblings.</p>
-<p>The &quot;current&quot; system is brought into scope automatically, however.</p>
-<p>What &quot;current&quot; means, is an early selector (&quot;select early and forget&quot;), usually determined by the user's operating system.</p>
+<p>The "current" system is brought into scope automatically, however.</p>
+<p>What "current" means, is an early selector ("select early and forget"), usually determined by the user's operating system.</p>
 <h2 id="consequences-2"><a class="header" href="#consequences-2">Consequences</a></h2>
 <blockquote>
 <p>What becomes easier or more difficult to do because of this change?</p>
 </blockquote>
 <!-- write an answer to this question below -->
 <p>The explicit handling of <code>system</code> in foreign contexts, where <code>system</code> is not a primary concern is largely eliminated.</p>
 <p>This makes using this framework a little easier for everybody, including packaging experts.</p>
-<p>Since <code>nixpkgs</code>, itself, exposes <code>nixpkgs.system</code> and packaging without <code>nixpkgs</code> is hardly imaginably, power-users still enjoy easy access to the &quot;current&quot; system, in case it's needed.</p>
+<p>Since <code>nixpkgs</code>, itself, exposes <code>nixpkgs.system</code> and packaging without <code>nixpkgs</code> is hardly imaginably, power-users still enjoy easy access to the "current" system, in case it's needed.</p>
 <hr />
 <h1 id="4-early-select-system-for-conceptual-untangling"><a class="header" href="#4-early-select-system-for-conceptual-untangling">4. Early select system for conceptual untangling</a></h1>
 <p>Date: 2022-04-01</p>
@@ -302,11 +302,11 @@ <h2 id="context-3"><a class="header" href="#context-3">Context</a></h2>
 </blockquote>
 <!-- write an answer to this question below -->
 <p>Building on the previous ADR, we saw why we hide <code>system</code> from plain sight.</p>
-<p>In that ADR, we mention &quot;select early and forget&quot; as a strategy to scope the current system consistently across the project.</p>
+<p>In that ADR, we mention "select early and forget" as a strategy to scope the current system consistently across the project.</p>
 <p>The current best practices for flakes postulate <code>system</code> as the second level selector of an output attribute.</p>
 <p>For current flakes, type primes over system.</p>
-<p>However, this design choice makes the lema &quot;select early and forget&quot; across multiple code-paths a pain to work with.</p>
-<p>This handling is exacerbated by the distinction between &quot;systemized&quot; and &quot;non-systemized&quot; (e.g. <code>lib</code>) output attributes.</p>
+<p>However, this design choice makes the lema "select early and forget" across multiple code-paths a pain to work with.</p>
+<p>This handling is exacerbated by the distinction between "systemized" and "non-systemized" (e.g. <code>lib</code>) output attributes.</p>
 <p>In the overall set of optimization goals of this framework, this distinction is of extraordinarily poor value, more so, that function
 calls are memoized during a single evaluation, which renders the system selector computationally irrelevant where not used.</p>
 <h2 id="decision-3"><a class="header" href="#decision-3">Decision</a></h2>
@@ -323,7 +323,7 @@ <h2 id="consequences-3"><a class="header" href="#consequences-3">Consequences</a
 <p>What becomes easier or more difficult to do because of this change?</p>
 </blockquote>
 <!-- write an answer to this question below -->
-<p>The motto &quot;select early and forget&quot; makes various code-paths easier to reason about and maintain.</p>
+<p>The motto "select early and forget" makes various code-paths easier to reason about and maintain.</p>
 <p>The Nix CLI completion won't respond gracefully to these changes.
 However, the Nix CLI is explicitly <em>not</em> a primary target of this framework.
 The reason for this is that the use cases for the Nix CLI are somewhat skewed towards the packager use case, but in any case are (currently) not purpose built for the DevOps use case.</p>
@@ -355,7 +355,7 @@ <h2 id="consequences-4"><a class="header" href="#consequences-4">Consequences</a
 </blockquote>
 <!-- write an answer to this question below -->
 <p>Users of Standard access packages as <code>nixpkgs.&lt;package-name&gt;</code>.</p>
-<p>Users that want to interact with nixos, do so by loading <code>nixos = import (inputs.nixpkgs + &quot;/nixos&quot;);</code> or similar.
+<p>Users that want to interact with nixos, do so by loading <code>nixos = import (inputs.nixpkgs + "/nixos");</code> or similar.
 The close coupling of the Nix Package Collection and NixOS now is broken.
 This suites well the DevOps use case, which is not <em>primarily</em> concerned with the unseparable union of the Nix Packages Collection and NixOS.
 It rather presents a plethora of use cases that content with the Nix Package Collection, alone, and where NixOS would present as a distraction.