Workspaces and namespaces

The workspace

A workspace root is a folder holding one of .runy.yaml, .runy.yml, .runy.json or .runy.toml. runy resolves the workspace of a command by walking up from the current directory to the nearest such file; --workspace <name> names one explicitly.

The config has one field today:

resources:
  - "products/**/.runy/*.yaml"

resources lists the globs of resource files, relative to the root. Empty or absent, it is **/.runy/*.yaml: every .runy/ folder in the tree. Files under a nested workspace root (a worktree checked out inside the tree with its own .runy.json) are skipped.

The daemon keeps each workspace’s state in a per-user cache folder (runy info folder prints it; ~/.cache/runy on macOS and Linux): the active namespaces, the journals, the folders that folder resources with cache: true get, and the worktrees. A link to the workspace’s part of it appears at .runy/.out under the root.

Namespaces

A namespace is a .runy/ folder. Every *.yaml file in it holds resources, and the namespace is named after the folder that holds .runy/:

.runy.json
Directoryproducts
- Directorynotes
  - Directory.runy
    dev.yaml notes
- Directorychalk
  - Directory.runy
    dev.yaml chalk
    namespace.yaml
- Directoryruny
  - Directory.runy
    ui.yaml runy

A namespace.yaml with kind: namespace and a name overrides the folder’s name. The root’s own .runy/ folder is the namespace named after the root folder.

Resource ids are namespace/kind/name, so two namespaces may each have a process/web. Inside a namespace a reference is local: process.web is this namespace’s web. Another namespace’s resources are reachable as ns.<namespace>.<kind>.<name> (see Expressions).

Activation

The daemon parses every namespace it finds and lists them, with their diagnostics, in runy ns and the console. It reconciles only the active ones:

runy ns                    # list: name, active, resource count, folder, diagnostics
runy ns up [name...]       # activate; no names: the namespace enclosing the cwd
runy ns down [name...]     # deactivate: stops its resources, frees its ports

┌───────────┬────────┬───────────┬────────────────┬─────────────┐
│ Namespace │ Active │ Resources │ Folders        │ Diagnostics │
├───────────┼────────┼───────────┼────────────────┼─────────────┤
│ blog      │ no     │ 1         │ products/blog  │ 0           │
│ chalk     │ no     │ 3         │ products/chalk │ 0           │
│ notes     │ no     │ 4         │ products/notes │ 0           │
│ runy      │ yes    │ 2         │ products/runy  │ 0           │
└───────────┴────────┴───────────┴────────────────┴─────────────┘

An active namespace’s files are inputs of the resolver and its resources run. An inactive namespace’s files are parsed for diagnostics only. Deactivating one removes its files from the resolver, which stops its resources, frees its ports and clears its statuses; resources in other namespaces that read them go Pending and keep running on their last applied spec.

The active set is persisted in the workspace’s cache folder (namespaces.json) and restored when the daemon starts. Nothing is activated implicitly. The console has a switch per namespace that does the same as up and down.