Skip to content

Commit b936ab7

Browse files
committed
docs(cli): a named artifact does not fall through the resolution chain (#4110 follow-up)
The artifact resolution-priority line reads as one fall-through list, so `--artifact` / `OS_ARTIFACT_PATH` look like they degrade to `<cwd>/dist/objectstack.json` when they do not resolve. They never did: a named source is used as given, without an existence check. That gap is what let #4110's "an absent artifact is not fatal" reach a case it was never meant to cover, so the doc now states the rule it always followed — named is used as-is and must exist, the fall-through is for the conventional locations only — alongside the fail-loud behaviour restored in this PR. Worth recording where the invariant was already written down: `os start`'s `resolveArtifactSource` deliberately does NOT exit on a missing `--artifact`, with the comment "Defer to serve.ts which already prints a precise error". #4110 silently removed that error; this PR restores what `os start` documents it depends on. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ve9HidCGRGtS2UjNPUGHSV
1 parent a0901f1 commit b936ab7

1 file changed

Lines changed: 10 additions & 0 deletions

File tree

content/docs/deployment/cli.mdx

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -323,6 +323,16 @@ os start
323323
**Resolution priority (artifact):** `--artifact` > `OS_ARTIFACT_PATH` > `<cwd>/dist/objectstack.json` > `<home>/dist/objectstack.json` > auto-compile from `objectstack.config.ts` (when present) > empty kernel.
324324
**Resolution priority (database):** `--database` > `OS_DATABASE_URL` > `DATABASE_URL` (legacy) > `file:<home>/data/objectstack.db`.
325325

326+
<Callout type="warn">
327+
A **named** artifact (`--artifact` or `OS_ARTIFACT_PATH`) does *not* participate
328+
in that fall-through: it is used as given, and a local path that does not exist
329+
**fails the boot** — naming the path and which of the two named it — instead of
330+
quietly continuing down the list. You asked for a specific artifact, so booting
331+
something else (or an empty kernel) would hide the typo behind a running server.
332+
The fall-through applies to the **conventional** locations only. Remote
333+
(`http(s)://`) sources cannot be checked up front and are validated when fetched.
334+
</Callout>
335+
326336
**What it boots:**
327337
- Reads the artifact's `manifest`, `objects`, `views`, `flows`, …
328338
- Auto-registers the platform services declared in `requires: [...]` (e.g. `ai`, `automation`, `analytics`, `auth`, `ui`). Declaring a **service** capability (`automation`, `analytics`, `ai`, `audit`, …) is a *requirement*: if its provider package isn't installed, boot **fails fast** with a clear error instead of silently starting without a capability you asked for. (`auth` and `ui` are tier-gated with their own opt-in rules — `auth`'s secret-gated skip is described below.)

0 commit comments

Comments
 (0)