@mostra/cli 0.9.0 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin.js +2 -2
- package/dist/bootstrap-BStzS_41.js +1 -0
- package/dist/{bootstrap-Dc-SQHRF.js → bootstrap-_iCl_HaO.js} +3 -2
- package/dist/bootstrap-_iCl_HaO.js.map +1 -0
- package/dist/{flush-C16w3JL8.js → flush-D648gCYs.js} +12 -3
- package/dist/flush-D648gCYs.js.map +1 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -2
- package/dist/reference/cli.md +210 -4
- package/dist/reference/diagnostics.json +171 -0
- package/dist/reference/errors/MOSTRA_ACTION_PAUSED.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_BUNDLE_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_NETWORK_FILESYSTEM.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_CONFIG_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_HOME_MOVING.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_HOME_SUSPENDED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_LIMIT_REACHED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_LOGIN_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_NOT_OWNER_INSTANCE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_NO_INSTANCE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_OPERATOR_UNAVAILABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_OWNER_OFFLINE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_PAUSED_BY_OPERATOR.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_RATE_LIMITED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_SIGN_IN_REQUIRED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_UNDER_REVIEW.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_UNREACHABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_PAUSED.md +23 -0
- package/dist/reference/self-hosting.md +130 -0
- package/dist/run-Bpg_ZRY8.js +1 -0
- package/dist/{run-DdYT3iHQ.js → run-BxYL-DaX.js} +333 -225
- package/dist/run-BxYL-DaX.js.map +1 -0
- package/dist/skill/SKILL.md +5 -3
- package/dist/skill/references/answers.md +36 -0
- package/dist/skill/references/mcp.md +9 -4
- package/dist/skill/references/sharing.md +55 -4
- package/dist/telemetry/flush-main.js +1 -1
- package/package.json +5 -5
- package/src/client.ts +1 -1
- package/src/commands/admin.ts +13 -3
- package/src/commands/authoring.ts +85 -3
- package/src/commands/index.ts +18 -3
- package/src/commands/remote.ts +209 -0
- package/src/commands/sharing.ts +33 -6
- package/src/commands/viewing.ts +20 -2
- package/src/detached.ts +3 -0
- package/src/docs.ts +12 -217
- package/src/exit.ts +2 -0
- package/src/mcp.ts +3 -21
- package/src/telemetry/store.ts +15 -4
- package/dist/bootstrap-Dc-SQHRF.js.map +0 -1
- package/dist/bootstrap-aaE5wFo9.js +0 -1
- package/dist/flush-C16w3JL8.js.map +0 -1
- package/dist/run-Bw4_6kcW.js +0 -1
- package/dist/run-DdYT3iHQ.js.map +0 -1
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
code: MOSTRA_SUBMIT_PAUSED
|
|
3
|
+
severity: error
|
|
4
|
+
phase: host
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
|
|
8
|
+
|
|
9
|
+
# MOSTRA_SUBMIT_PAUSED
|
|
10
|
+
|
|
11
|
+
Artifact paused, no answers taken. Severity: error. Phase: host.
|
|
12
|
+
|
|
13
|
+
## What it means
|
|
14
|
+
|
|
15
|
+
The artifact is paused (`mostra pause`, or its server's operator paused it). A paused artifact stays viewable and its links stay valid, but it takes no submissions until it is resumed. Nothing was recorded, and the draft stays as it was.
|
|
16
|
+
|
|
17
|
+
## How to fix it
|
|
18
|
+
|
|
19
|
+
The owner resumes it with `mostra resume <artifact>`; a pause by the server's operator is resumed only by the operator.
|
|
20
|
+
|
|
21
|
+
## Hint
|
|
22
|
+
|
|
23
|
+
Wait until the page is resumed, then submit again; the draft is kept.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# Self-hosting the remote server
|
|
2
|
+
|
|
3
|
+
The remote server hosts shared pages so their links keep working while the machine that shared them sleeps. It also hosts the remote MCP endpoint for chat apps. You run it as one container behind a TLS front. This page shows the shape with Caddy. Any TLS terminator that keeps the request's `Host` and adds `X-Forwarded-For` works the same way.
|
|
4
|
+
|
|
5
|
+
## What you need
|
|
6
|
+
|
|
7
|
+
- **A host name for the API origin**, such as `api.example.com`. Owners sign in and connect there, chat apps reach `/mcp` there, and version files upload there.
|
|
8
|
+
- **A user-content domain of its own**, such as `example-usercontent.com`. Its apex serves the hosted shell, and each shared page gets a random label under it (`<label>.example-usercontent.com`). Use a registrable domain that serves nothing else, and keep the API origin off it. A page on it can set cookies for the whole domain, so nothing else should live there.
|
|
9
|
+
- **DNS** for the API host, the user-content apex and the wildcard `*.example-usercontent.com`, all pointing at your front. Labels are one level deep, so one wildcard certificate covers every page.
|
|
10
|
+
- **One machine** with Docker and a local disk. The data directory can't be on a network filesystem: the server refuses NFS, SMB and network FUSE mounts at start.
|
|
11
|
+
|
|
12
|
+
## Configuration
|
|
13
|
+
|
|
14
|
+
The server reads a JSON file (`--config`) and `MOSTRA_SERVER_<KEY>` variables. A variable overrides the file's key. It holds JSON, or a plain string for `apiOrigin`, `operator` and `scheme`. If the server can't use a key, it stops before serving anything and names the key (`MOSTRA_REMOTE_CONFIG_INVALID`).
|
|
15
|
+
|
|
16
|
+
```json
|
|
17
|
+
{
|
|
18
|
+
"apiOrigin": "https://api.example.com",
|
|
19
|
+
"domains": { "active": "example-usercontent.com" },
|
|
20
|
+
"trustedProxies": ["172.31.230.0/24"],
|
|
21
|
+
"identityProviders": [
|
|
22
|
+
{
|
|
23
|
+
"id": "github",
|
|
24
|
+
"kind": "github",
|
|
25
|
+
"label": "GitHub",
|
|
26
|
+
"clientId": "<the OAuth app's client ID>",
|
|
27
|
+
"clientSecretFile": "/run/secrets/github"
|
|
28
|
+
}
|
|
29
|
+
],
|
|
30
|
+
"rateLimits": {
|
|
31
|
+
"perIp": { "submissions": { "count": 120, "per": "1m" } },
|
|
32
|
+
"perLink": { "submissions": { "count": 600, "per": "1m" } }
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
| Key | What it does |
|
|
38
|
+
|---|---|
|
|
39
|
+
| `apiOrigin` | The API origin, `https:` |
|
|
40
|
+
| `domains.active`, `domains.spares` | The user-content domain new links use, and older ones that issued links keep working on. To move off a domain, make a spare active and restart the server |
|
|
41
|
+
| `trustedProxies` | Addresses or CIDR ranges whose `X-Forwarded-For` the server believes. It reads the header from the right and takes the first address that isn't a trusted proxy. Rate limits count IPv6 clients per /64 (`rateLimits.ipv6Prefix`) |
|
|
42
|
+
| `identityProviders` | How people sign in: `github` (an OAuth app), `oidc` (any OpenID Connect provider: `issuer`, `clientId`, `clientSecretFile`) or `development` (trusts any typed name; for tests only, never on a public server) |
|
|
43
|
+
| `rateLimits` | Rates as `{ "count", "per" }`: `perIp.submissions` and `perLink.submissions` for answers, `perLink.relayedRuns` for actions, and `perIp.requests` for every request an address sends (a health check aside). Past a rate the answer is 429 with `Retry-After`; a page says to try again shortly and keeps the draft. A key left out is no limit |
|
|
44
|
+
| `relay`, `homes`, `ledger` | The relay's waiting-run cap and drain rate, how long an idle hosted home stays open, and the ledger's WAL checkpoint (`0` for a backup replicator) |
|
|
45
|
+
| `operator` | The path of an operator module, which adds limits, metering, accounts and abuse handling through the operator ports (`@mostra/protocol/operator`). Without one, every port keeps its no-op default |
|
|
46
|
+
|
|
47
|
+
For GitHub sign-in, create an OAuth app with the callback `https://api.example.com/signin/github/callback`. For OpenID Connect, register the redirect URI `https://api.example.com/signin/<id>/callback`. Keep each client secret in a file that only the container's user (UID 10001) can read.
|
|
48
|
+
|
|
49
|
+
## Running it with Caddy
|
|
50
|
+
|
|
51
|
+
The image is `ghcr.io/mostra-dev/mostra-server`, tagged with each release's version, for `linux/amd64` and `linux/arm64`. It runs `mostra-runtime server` as a non-root user. It listens on port 8080 and keeps everything in `/data`: hosted homes, version files and the server's keys. Append `--config <file>` to its command, or set the `MOSTRA_SERVER_*` variables.
|
|
52
|
+
|
|
53
|
+
`compose.yaml`:
|
|
54
|
+
|
|
55
|
+
```yaml
|
|
56
|
+
networks:
|
|
57
|
+
front:
|
|
58
|
+
ipam:
|
|
59
|
+
config:
|
|
60
|
+
- subnet: 172.31.230.0/24
|
|
61
|
+
volumes:
|
|
62
|
+
data: {}
|
|
63
|
+
caddy-data: {}
|
|
64
|
+
services:
|
|
65
|
+
mostra-server:
|
|
66
|
+
image: ghcr.io/mostra-dev/mostra-server:<version>
|
|
67
|
+
command: ["--config", "/config/server.json"]
|
|
68
|
+
restart: unless-stopped
|
|
69
|
+
networks: [front]
|
|
70
|
+
read_only: true
|
|
71
|
+
tmpfs: [/tmp]
|
|
72
|
+
volumes:
|
|
73
|
+
- data:/data
|
|
74
|
+
- ./server.json:/config/server.json:ro
|
|
75
|
+
- ./github-secret:/run/secrets/github:ro
|
|
76
|
+
caddy:
|
|
77
|
+
image: <caddy built with the caddy-dns module for your DNS provider>
|
|
78
|
+
restart: unless-stopped
|
|
79
|
+
networks: [front]
|
|
80
|
+
ports: ["80:80", "443:443", "443:443/udp"]
|
|
81
|
+
volumes:
|
|
82
|
+
- ./Caddyfile:/etc/caddy/Caddyfile:ro
|
|
83
|
+
- ./dns-token:/run/secrets/dns-token:ro
|
|
84
|
+
- caddy-data:/data
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`Caddyfile`:
|
|
88
|
+
|
|
89
|
+
```caddyfile
|
|
90
|
+
{
|
|
91
|
+
servers {
|
|
92
|
+
# A sibling page can fill the domain's cookie jar: pass up to 1 MiB of headers.
|
|
93
|
+
max_header_size 1MiB
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
api.example.com {
|
|
98
|
+
reverse_proxy mostra-server:8080
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
example-usercontent.com, *.example-usercontent.com {
|
|
102
|
+
tls {
|
|
103
|
+
dns cloudflare {file./run/secrets/dns-token}
|
|
104
|
+
}
|
|
105
|
+
reverse_proxy mostra-server:8080
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
The wildcard certificate needs the DNS-01 challenge, so Caddy needs a build with your DNS provider's module (`xcaddy build --with github.com/caddy-dns/<provider>`) and a token that may edit the zone's records, kept in the file `dns-token` beside the `Caddyfile` (readable by the user Caddy runs as, and by nobody else) and read by `{file.…}`, so it is in no environment a process listing or a log can show. Caddy keeps the request's `Host` and adds `X-Forwarded-For`, and the server believes that header only from the network `trustedProxies` names.
|
|
110
|
+
|
|
111
|
+
Check the server once it runs:
|
|
112
|
+
|
|
113
|
+
```sh
|
|
114
|
+
curl https://api.example.com/health # {"status":"ok",…}
|
|
115
|
+
curl https://api.example.com/.well-known/oauth-authorization-server # the sign-in metadata
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
An owner then links a machine with `mostra login https://api.example.com` and shares a page with `mostra share <dir> --cloud`. A chat app connects to `https://api.example.com/mcp`.
|
|
119
|
+
|
|
120
|
+
## Fronts and request headers
|
|
121
|
+
|
|
122
|
+
Hosted pages use no cookies, and the server drops every `Cookie` header unread. A tenant's page can still fill the user-content domain's cookie jar, and browsers then send up to about 720 KiB of cookies with each request. The server accepts headers up to 1 MiB, so such a jar never costs another page its session. Your front has to pass them too. Caddy's default is 16 KiB, so the Caddyfile above raises it with `max_header_size 1MiB`. A CDN or proxy whose limit is smaller fails every page on the domain for a browser whose jar a sibling page filled.
|
|
123
|
+
|
|
124
|
+
## Backups and restores
|
|
125
|
+
|
|
126
|
+
Each hosted home's ledger is SQLite in WAL mode with normal locking, so a WAL replicator such as Litestream can read it live from its own process. Back up the whole data directory. After restoring a home, or the whole directory, by hand, start the server with `--restored <homeId>` or `--restored all`. The restored homes then rotate their incarnations before they serve anything, so owners never mistake reused cursors for ones they already copied. Each owner's machine also notices a home that holds less than it copied, and records the gap as `remote.regressed`.
|
|
127
|
+
|
|
128
|
+
## What the open server doesn't do
|
|
129
|
+
|
|
130
|
+
It imposes no quota, link expiry or automatic pause, deletes nothing on its own, and sends no email or webhook. Plans, quotas, billing, abuse scoring, placing homes across machines, backup automation and outside domains come from an operator module through the operator ports. An operator pauses, quarantines, suspends and removes through the server handle the module receives.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { t as run } from "./run-BxYL-DaX.js";
|