NOTE(2019-08): This document is severely `OUTDATED and SEMANTICALLY UNRELIABLE`. This content is what used to be in DEVOPS.md, is relatively old and needs to be revised. The specification needs to be extracted to be a separate document from the devops workflows.
valos-vault-1.1: ValOS packages are all the npmjs.com packages with @valos scope which don't have cyclic dependencies with other @valos scope packages.
valos-vault-1.2: Valaa Open System (ValOS is defined to be the contents of all ValOS packages and nothing else.
valos-vault-1.3: ValOS specification consists of all files in all ValOS packages whose path in the package matches the JS regex /^specifications\/\w*.md$/ and nothing else.
valos-vault-1.4: Rules in a package are considered to be more specific than the rules in its package dependency tree. More specific rules take precedence.
valos-vault-1.5: All packages which conform to ValOS specification are called ValOS packages. These packages are inclusively considered part of the ValOS ecosystem.
valos-vault-2.1: A domain is the collection of all the systems, interactions and dynamics which exclusively serve a particular purpose.
valos-vault-2.2: A domain must define the purpose, describe its producers and consumers and should provide a direction for technical and operational structure as well.For example the @valos/kernel domain provides the essential central ValOS code for developing new ValOS infrastructure software. Its main producers are the kernel software developers and its consumers are the infrastructure software developers. It revolves around developing code as library packages.
valos-vault-3.1: valma is installed with npm install -g valma or as a package dependencyThis installs the global CLI command vlm . At its core valma is a command dispatcher to valma scripts in various command pools.
valos-vault-3.2: valma searches the scripts first from the package.json scripts pool, then from ./node_modules/.bin/depends pool and lastly from the OS-specific variant of /usr/binglobal pool.As an example typing vlm status in some directory context would forward the command to valma.bin/valma-status first if one exists and falling back to the more generic versions if not. The call eventually resolves at the global /usr/bin/valma-status . Its implementation then calls vlm .status/**/* which calls all scripts which match the glob .status/**/* and are visible on the execution context pools (the scripts called by vlm status are known as valma status scripts).
valos-vault-3.3: A package can export valma scripts using npm package.json bin section and by prefixing the exported name with _vlm_ as usual. These scripts will be available for all packages depending on this package in their depends pool.Running vlm with no arguments lists all available commands grouped by pool in current directory context.
valos-vault-3.5: valma can be used in programmatic contexts to run valma scripts. When done so, valma must be added as a dependency.This happens just like with the CLI by using vlm <command> [<args>] . ("npx -c" would be the alternative but it's slow and limited).
valos-vault-3.5.1: valma ensures that node environment is loadedThe environment is loaded only once even for recursive script invokations.
valos-vault-3.5.2: valma ensures that 'vlm' is always found in pathThis is so that valma scripts can call 'vlm' even valma is not globally installed as long as valma has been installed as a dependency.
valos-vault-3.5.3: valma ensures that the most specific 'vlm' version is used to evaluate a command, preferring scripts over depended over global.This is so that toolkits can precisely control the whole toolchain in their dependencies.
valos-vault-4.1.1: An utility is a domain with a well-defined operational purpose.
valos-vault-4.1.2: utility must explicitly define the payload it provides to its consumers as well as the providers, tools and workflows used to manage that payload.Below is a rough correlation of similar concepts across utilities.
valos-vault-4.2.1: ValOS tools should use git as the files provider.While github.com is the de facto standard provider and the typical choice it must *not* be _required_.
valos-vault-4.2.2: All git providers must be fully supported by all ValOS tools and libraries.
valos-vault-4.3.1: The packages utility payload is npmjs.com packagesThese packages can be libraries, toolsets or prebuilt release runtimes - any sets of files really. The raison d'être for packages is when several different consumers depend on the same set of files which are also expected to undergo periodic development. The files thus need versioning, dependency management and automated distribution - this all is provided by npm.
TODO(iridian): Figure out whether this is actually the most meaningful place to assign this semantic border. A specific term for non-authenticated chronicles capable of running only on standard runtime is useful, but how useful actually?