shell-architecture

OpenShellOrg thesis: structured shell pipelines, SOS relationship, Nushell advocacy.
Explore the docs

Report Bug · Request Feature

About The Project

Standards and explanation for OpenShellOrg’s structured-shell direction — not a product repo (yet).

Published docs: https://openshellorg.github.io/docs/shell-architecture/

Thesis (short)

1. Structured data pipelines beat treating stdout as both data and display. We endorse Nushell as the Unix-centric reference implementation. PowerShell pioneered object pipelines; we recommend Nushell going forward.

2. SOS (flag syntax) and structured shells are complementary layers — spelling options consistently does not replace typed pipelines, and vice versa.

3. DevCentr recommends and configures; OpenShellOrg standardizes and builds companion tooling.

4. Future topics include display vs transport decoupling, terminal protocol notes, TUI vs structured stdout, and speculative mixed-fonts research.

5. Open Shell in D — default oso mode; Nushell reproduced as nu compatibility baseline. See docs/modules/ROOT/pages/open-shell.adoc.

6. Env refresh / shell-host — planned products so stale PATH is a non-issue (especially for Nushell users); see shell-host-and-env-refresh.

(back to top)

Usage

Webview run surface demo

Companion demo for the Webview run surface architecture page — flicker-free zoned live updates over an append-only ops.jsonl (filesystem I/O, not document.write):

pnpm demo:webview-run-surface

Open http://localhost:3847/. Details: demos/webview-run-surface/README.md.

Mermaid diagram sources

Four entrypoint-dispatch figures are authored as Mermaid under docs/modules/ROOT/partials/diagrams/ and baked to SVG in docs/modules/ROOT/images/. After editing .mmd or .theme.json sources, regenerate and check locally before merge — see diagrams/README.adoc (pnpm diagrams, then pnpm diagrams:check or pnpm test). Hub CI in openshellorg/docs does not re-run that bake.

Documents

Antora component under docs/ (assembled into the org docs site):

• Thesis

• Layers

• SOS and structured shells

• Dev-Centr

• DevCentr and OpenShellOrg

• Shell Host and Env Refresh

• Stance

• Future topics

Related projects

• docs — SOS certification and flag syntax

• nu-require — require / relaunch under Nushell

• nu-emit — emit structured rows from C without hand-JSON

• project-map — project-type + file-role API; lsgrouped CLI

• Planned: openshellorg/env-refresh

• Forked: openshellorg/terminal (Windows Terminal + env-refresh UX)

• Nushell

• Public site domain: opensh.org ({OSO} Certified - opensh.org)

Not NVIDIA OpenShell — that is agent sandboxing.

(back to top)

License

MIT — see LICENSE

(back to top)

Contact

Open Shell Org — openshell@devcentr.org

• Project: https://github.com/openshellorg/shell-architecture

• Site: https://openshellorg.github.io

(back to top)