Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

7.2 KB
Raw Blame

Contributing

MSO is a focused, single-owner project. Issues and pull requests are welcome, but changes should preserve the narrow security and deployment model.

Setup

bun install
cp .env.example .env.local
bun run dev

Set OS_LOGIN_PASSWORD and OS_SESSION_SECRET for live auth. The mock adapters let most UI work proceed without VPS credentials or host access.

Before a PR

Run:

bash scripts/gates-12.sh full
bun run verify
node scripts/check-docs.mjs
bash scripts/verify-build.sh

Start with bash scripts/gates-12.sh full. It is the local mirror of the GitHub Actions verify job: the same checks in the same order, so a red build shows up on your machine instead of in your Actions minutes. full adds coverage, the production build and every browser journey; the default fast mode is about two minutes and skips the slow three.

A clean run ends with either of these, and both are green:

mode=full  passed=17  failed=0  skipped=0
mode=full  passed=16  failed=0  skipped=1

The difference is the bundle budget, which verify-build.sh enforces inside the same run rather than twice, so it reports as SKIP rather than PASS.

Run only one gates-12.sh at a time per worktree. Two concurrent full runs corrupt each other in ways that look like real defects: vitest refuses to start because both write the same coverage/ directory, and verify-build.sh copies the tree into /tmp per run, so two copies can exhaust the tmpfs. fast mode alongside full is also unsafe: they share /tmp/gate-out.txt, so one run's failure text can appear under the other's name.

bun run verify covers typecheck, lint, the Vitest suite, repository checks and the high/critical dependency audit. verify-build.sh compiles a throwaway copy of HEAD so it is safe even when the checkout is also the production WorkingDirectory.

Do not run a bare production build inside a live production checkout merely to prove that code compiles; replacing .next underneath next start can create a chunk mismatch until the service is replaced.

Where the CI work actually runs

The verify job is fully reproducible locally; the security workflows are not yet, and this is deliberate rather than an oversight:

Workflow Local equivalent
ci.yml verify bash scripts/gates-12.sh full
ci.yml native-host (macOS/Windows) not reproducible; needs those runners
ci.yml dependency-watch bun run audit:strict plus npm audit --prefix scripts/install/node-gyp --omit=dev --audit-level=high
security-core.yml partially: docs/SELF-HOSTED-CI.md lane is BLOCKED
codeql.yml, dast.yml, dependency-review.yml, scorecard.yml, security-alerts.yml, codex-security.yml no local equivalent

bun run ci:plan prints the repository-owned CI plan, and bun run ci:verify --sha "$(git rev-parse HEAD)" runs it. The security and release profiles return BLOCKED on purpose: the scanner adapters are written but not yet verified end to end, and a blocked lane must never be reported as a pass. See docs/SELF-HOSTED-CI.md for the migration matrix and the evidence rules.

You can still run the three scanners by hand with the exact image digests the workflows pin. All three have been verified locally:

docker run --rm -v "$PWD:/src:ro" semgrep/semgrep@sha256:f1f7b71861c7b28b6e0f661225a2c4f58a484f5d0f182465c6d6b3b22f972ade \
  semgrep scan --metrics=off --config=p/javascript --config=p/typescript \
  --config=p/owasp-top-ten --strict --error \
  --exclude=node_modules --exclude=.next --exclude=coverage /src

docker run --rm -v "$PWD:/repo" zricethezav/gitleaks@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f \
  git --gitleaks-ignore-path /repo/.gitleaksignore /repo

docker run --rm -v "$PWD:/src:ro" ghcr.io/google/osv-scanner@sha256:8108ae94eadea5a02c9bec6e646909d5b790b44bd62d7f5b7f0b1d6d0ffc7734 \
  scan source --recursive /src

The --exclude flags are not decoration. CI scans a clean checkout; a working tree also has node_modules, .next and coverage, and scanning those produces findings in third-party code that CI never sees. Without them Semgrep reported 7 findings here and 0 with them.

Run the Gitleaks command from the main checkout, not from a git worktree. A worktree's .git is a file pointing at the real git dir, so the scanner sees no repository and reports 0 commits scanned followed by no leaks found. That reads like a pass and proves nothing: the same command in the main checkout scanned 1165 commits and is the only form of the check that means anything.

The OSV result depends on bun.lock. It reports No issues found on a tree that already carries the minimatch override to 11.0.3, and two medium findings (minimatch 3.1.5 and 10.2.6) on one that does not. If you see those two, the fix exists and your base predates it, so rebase rather than adding a second override block.

Two things these catch that the gates do not. Semgrep fails on a parse warning under --strict even with zero findings, so a generic type argument on await importOriginal<...>() in a test breaks the required check; apply the type with a cast on its own const instead. Gitleaks scans all history, so a secret in an old commit fails the check regardless of what your diff contains.

The committed source of truth for pre-push policy is scripts/gates.sh. The actual .git/hooks/pre-push file is intentionally a tiny untracked shim. Install/reinstall it with:

bash scripts/gates.sh --install

A healthy push runs the shared typecheck/lint/test path (or in-repo fallback), cycle/docs/ changelog checks, dependency audit and the out-of-tree build. It should end with both:

audit: clean at high/critical.
build: HEAD compiles (out-of-tree).

The GitHub CI workflow is still useful for a clean-checkout dependency/install proof, especially after changes to package.json, bun.lock or installer/release scripts.

Conventions

The current architecture is in docs/ARCHITECTURE.md and the documentation map is docs/README.md. Reviewers will hold changes to these rules:

  • vertical application slices live under frontend/slices/<slug>/;
  • cross-slice imports use public barrels;
  • host operations flow through lib/host instead of reimplementing path/process guards in routes or components;
  • keep files small/single-purpose where practical and use the existing UI primitives/tokens;
  • keep responsive/mobile behaviour first-class;
  • preserve the single catch-all app routing model;
  • use conventional commit subjects.

When you add/remove/rename a current capability, update the relevant current reference doc in the same change. scripts/check-docs.mjs catches selected machine-verifiable drift but cannot infer every semantic change.

Releasing maintainer changes

Normal contributor PRs should not deploy production. The maintainer release path after a verified merge is:

bun run ship "feat(scope): describe the verified change"

A Git push by itself is not deployment. See docs/DEVELOPMENT.md.

Security issues

Do not open a public issue containing exploit details or secrets. Follow SECURITY.md.