Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions projects/start-os/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,9 @@ monorepo-wide rules, and [ARCHITECTURE.md](ARCHITECTURE.md) and
- Type-check the runtime: `cd projects/start-os/container-runtime && npm run check`.
- Build the UI: `make start-os-ui` (or `make start-os-uis` for ui + setup-wizard).
- Tests: `make test` (Rust + SDK + container-runtime), or `make start-core-test`.
- Format: `make start-os-format` / `make start-os-format-check`.
- Format: `make start-os-format` / `make start-os-format-check` (Rust only);
TS/web/container-runtime formatting runs through `make web-format` (root
prettier config).
- Regenerate `start-container` man pages (committed under `man/`):
`cargo test -p start-core export_manpage_start_container`.

Expand All @@ -49,8 +51,10 @@ monorepo-wide rules, and [ARCHITECTURE.md](ARCHITECTURE.md) and
- **`unshare-userns` must stay a multi-call applet**, not a CLI subcommand: it
calls `unshare(CLONE_NEWUSER)`, which the kernel rejects on a multi-threaded
process. See the comment in `src/bin/start-container.rs`.
- **Don't normalize style across components.** The container-runtime uses double
quotes + no semicolons (its own prettier config); the SDK uses single quotes.
- **One prettier config.** All TS (web, container-runtime) is governed by the
root `.prettierrc.json` + `.prettierignore`; run prettier from the repo root
so the ignore applies (`__fixtures__/` etc. must stay unformatted). Don't add
per-component prettier configs or scripts.
- **Don't edit generated binding files** like
`shared-libs/ts-modules/start-core/lib/osBindings/index.ts` or `projects/start-sdk/s9pk.mk`.
- **Ask before destructive `make` recipes** — `update*`, `reflash`, `wormhole*`,
Expand Down
5 changes: 3 additions & 2 deletions projects/start-os/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,13 +123,14 @@ make test # Rust + SDK + container-runtime
make start-core-test # backend only
```

The container-runtime has its own test suite and prettier config (double quotes, no semicolons) — see [container-runtime/CONTRIBUTING.md](container-runtime/CONTRIBUTING.md). Note CI builds a multi-platform matrix (apple-darwin + aarch64/x86_64/riscv64 musl); local `cargo check` is linux-only, so consider platform-specific impact.
The container-runtime has its own test suite — see [container-runtime/CONTRIBUTING.md](container-runtime/CONTRIBUTING.md). Note CI builds a multi-platform matrix (apple-darwin + aarch64/x86_64/riscv64 musl); local `cargo check` is linux-only, so consider platform-specific impact.

## Formatting

```sh
make start-os-format # format this product (core bins + web + container-runtime)
make start-os-format # format this product's Rust (core bins + backup-fs)
make start-os-format-check # CI-style check
make web-format # prettier (root config) — covers web + container-runtime
```

## Cross-layer changes
Expand Down
7 changes: 3 additions & 4 deletions projects/start-os/build.mk
Original file line number Diff line number Diff line change
Expand Up @@ -212,13 +212,12 @@ start-os-clean:
rm -rf projects/start-os/build/lib/firmware projects/start-os/build/lib/migration-images
rm -rf projects/start-os/build/image-recipe/deb

# OS bins + backup-fs (Rust) and the container-runtime (its own prettier config).
# The ui/setup-wizard web apps are formatted by `web-format` (whole Angular workspace).
# The ui/setup-wizard web apps and the container-runtime are formatted by
# `web-format`/`web-format-check` (root prettier config, run from the repo root so
# the root .prettierignore applies). This target is just the Rust crates.
.PHONY: start-os-format start-os-format-check
start-os-format:
$(FMT) cargo fmt -p start-os -p startos-backup-fs
npm --prefix projects/start-os/container-runtime run format

start-os-format-check:
$(FMT) cargo fmt --check -p start-os -p startos-backup-fs
npm --prefix projects/start-os/container-runtime run format:check
4 changes: 2 additions & 2 deletions projects/start-os/container-runtime/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Run from the monorepo root (`/path/to/start-os`):
cd projects/start-sdk && make bundle && cd - # build SDK dependency first
npm --prefix projects/start-os/container-runtime ci # install deps
npm --prefix projects/start-os/container-runtime run check # tsc --noEmit (type-check)
npm --prefix projects/start-os/container-runtime run build # prettier + clean + tsc -> dist/
npm --prefix projects/start-os/container-runtime run build # clean + tsc -> dist/
npm --prefix projects/start-os/container-runtime test # jest (ts-jest)
make container-runtime-test # SDK + jest via top-level Makefile
```
Expand All @@ -30,7 +30,7 @@ Tests are Jest + `ts-jest` (`jest.config.js`, `rootDir: ./src`). `mime` is mocke
## Gotchas

- **Depends on the _built_ SDK at `../../start-sdk/dist`** (declared in `package.json` as `"@start9labs/start-sdk": "file:../../start-sdk/dist"`) **and on `@start9labs/start-core` at `../../../shared-libs/ts-modules/start-core/dist`** (for what were the deep `base/lib/...` imports). Editing `projects/start-sdk/` or `shared-libs/ts-modules/start-core/` source alone has no effect here — rebuild first: `cd projects/start-sdk && make bundle` (which builds start-core and bundles it). The Makefile target `projects/start-os/container-runtime/package-lock.json` also depends on `projects/start-sdk/dist/package.json`, so a stale SDK can break `npm ci`/`check`/`test`.
- **Style: double quotes, no semicolons.** Prettier config lives in `package.json` (`semi: false`, `singleQuote: false`, `trailingComma: "all"`, `tabWidth: 2`). This differs from `start-sdk` / `shared-libs/ts-modules` (single quotes there) — do NOT "normalize" to single quotes. `npm run build` runs Prettier `--write` before compiling.
- **Formatting is the root prettier config** (`.prettierrc.json` at the repo root), applied via `make format` / `make web-format` from the repo root. Never run prettier from inside this directory: the root `.prettierignore` (which protects `__fixtures__/`) only applies when prettier runs from the root cwd.
- **`CLAUDE.md` is just `@AGENTS.md`** — edit this file, not `CLAUDE.md`.

## Image build (gotchas)
Expand Down
16 changes: 6 additions & 10 deletions projects/start-os/container-runtime/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Run from the monorepo root:
```bash
npm --prefix projects/start-os/container-runtime ci # install deps
npm --prefix projects/start-os/container-runtime run check # type-check (tsc --noEmit)
npm --prefix projects/start-os/container-runtime run build # prettier + clean + tsc -> dist/
npm --prefix projects/start-os/container-runtime run build # clean + tsc -> dist/
```

Or `cd projects/start-os/container-runtime` first and drop the `--prefix`.
Expand All @@ -46,15 +46,11 @@ Jest with `ts-jest` (`jest.config.js`, `rootDir: ./src`). The `mime` module is m

## Formatting

Prettier config lives in `package.json`:

- `trailingComma: "all"`, `tabWidth: 2`, `semi: false`, `singleQuote: false`.

The runtime uses **double quotes**, unlike `start-sdk` and `shared-libs/ts-modules` (single quotes there) — do not normalize. `npm run build` runs Prettier `--write` before compiling, so formatting is applied automatically during a build.

From the monorepo root, the canonical formatter is the top-level make target (container-runtime folds into the start-os product):
The root prettier config (`.prettierrc.json` at the repo root) governs this directory — there is no local config or format script. Format from the monorepo root:

```bash
make start-os-format # write formatting
make start-os-format-check # CI read-only check
make web-format # prettier --write over the whole repo
make web-format-check # CI read-only check
```

Never run prettier from inside this directory: the root `.prettierignore` only applies when prettier runs from the root cwd, and it must apply — it protects `__fixtures__/` (byte-exact test fixtures) from being reformatted.
19 changes: 1 addition & 18 deletions projects/start-os/container-runtime/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 1 addition & 4 deletions projects/start-os/container-runtime/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,7 @@
"module": "./index.js",
"scripts": {
"check": "tsc --noEmit",
"format": "prettier . '!tmp/**' --write",
"format:check": "prettier . '!tmp/**' --check",
"build": "prettier . '!tmp/**' --write && rm -rf dist && tsc",
"build": "rm -rf dist && tsc",
"tsc": "rm -rf dist; tsc",
"test": "jest -c ./jest.config.js"
},
Expand Down Expand Up @@ -39,7 +37,6 @@
"@types/jsonpath": "^0.2.4",
"@types/node": "^20.11.13",
"jest": "^29.7.0",
"prettier": "^3.2.5",
"ts-jest": "^29.2.3",
"typescript": ">5.2"
}
Expand Down
Loading