@mostra/cli 0.10.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 +1 -1
- package/dist/{flush-znWmNZA1.js → flush-D648gCYs.js} +2 -1
- package/dist/flush-D648gCYs.js.map +1 -0
- package/dist/index.js +1 -1
- package/dist/reference/cli.md +67 -1
- package/dist/reference/diagnostics.json +81 -0
- package/dist/reference/errors/MOSTRA_ACTION_PAUSED.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_NO_INSTANCE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_OPERATOR_UNAVAILABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_PAUSED_BY_OPERATOR.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_UNDER_REVIEW.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-Aq4HVIY0.js → run-BxYL-DaX.js} +104 -215
- package/dist/run-BxYL-DaX.js.map +1 -0
- package/dist/skill/SKILL.md +4 -2
- package/dist/skill/references/mcp.md +8 -3
- package/dist/skill/references/sharing.md +1 -0
- package/dist/telemetry/flush-main.js +1 -1
- package/package.json +5 -5
- package/src/commands/admin.ts +2 -2
- package/src/commands/index.ts +3 -1
- package/src/commands/remote.ts +99 -3
- package/src/detached.ts +1 -0
- package/src/docs.ts +12 -217
- package/src/mcp.ts +3 -21
- package/dist/flush-znWmNZA1.js.map +0 -1
- package/dist/run-Aq4HVIY0.js.map +0 -1
- package/dist/run-D1U_RFEP.js +0 -1
|
@@ -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";
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
import { a as GLOBAL_FLAGS, c as parseCommandLine, d as EXIT, f as exitCodeFor, l as topWords, m as defineCommand, o as durationMs, p as commandName, r as progressReporter, s as globalFlags, u as usage } from "./bootstrap-_iCl_HaO.js";
|
|
2
|
-
import { _ as packageRoot, a as detachedEnvironment, c as durationBucket, d as mcpSessionFields, f as buildEndpoint, g as fromSource, h as cliVersion, i as detachedDirectory, l as minute, m as truthy, n as startFlusher, o as TelemetryEvent, p as decide, r as TelemetryStore, s as catalogCodes, u as detectHarness } from "./flush-
|
|
2
|
+
import { _ as packageRoot, a as detachedEnvironment, c as durationBucket, d as mcpSessionFields, f as buildEndpoint, g as fromSource, h as cliVersion, i as detachedDirectory, l as minute, m as truthy, n as startFlusher, o as TelemetryEvent, p as decide, r as TelemetryStore, s as catalogCodes, u as detectHarness } from "./flush-D648gCYs.js";
|
|
3
3
|
import { spawn } from "node:child_process";
|
|
4
4
|
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
5
|
-
import {
|
|
6
|
-
import { ARTIFACT_PROGRESS, CLI_CLIENT_NAME, DEFAULT_DOCS_BASE, DEV_NOTIFY, FieldOp, HOST_PROTOCOL_REVISIONS, LineSplitter, MutationId, RpcError, RpcPeer, artifactCreateMethod, artifactExportMethod, artifactGetMethod, artifactImportMethod, artifactListMethod, artifactPublishMethod, artifactVerifyMethod, createDiagnostic, depsAddMethod, devStartMethod, devStopMethod, diagnosticCatalog, encodeLine, gcRunMethod, instanceCheckMethod, instanceStatusMethod, livePushMethod, mostraInitializeMethod, mostraShutdownMethod, remoteLoginMethod, remoteLoginWaitMethod, remoteLogoutMethod, resultsGetMethod, secretDeleteMethod, secretListMethod, secretSetMethod, shareListMethod, shareStartMethod, shareStopMethod, stateGetMethod, statePatchMethod, viewDefaultMethod, viewLaunchMethod, viewRevokeMethod, viewRotateMethod, viewUrlMethod, waitMethod } from "@mostra/protocol";
|
|
5
|
+
import { isAbsolute, join, resolve, win32 } from "node:path";
|
|
6
|
+
import { ARTIFACT_PROGRESS, CLI_CLIENT_NAME, DEFAULT_DOCS_BASE, DEV_NOTIFY, FieldOp, HOST_PROTOCOL_REVISIONS, LineSplitter, MutationId, RpcError, RpcPeer, artifactCreateMethod, artifactExportMethod, artifactGetMethod, artifactImportMethod, artifactListMethod, artifactPauseMethod, artifactPublishMethod, artifactVerifyMethod, createDiagnostic, depsAddMethod, devStartMethod, devStopMethod, diagnosticCatalog, encodeLine, gcRunMethod, instanceCheckMethod, instanceStatusMethod, livePushMethod, mostraInitializeMethod, mostraShutdownMethod, remoteLinkMethod, remoteLoginMethod, remoteLoginWaitMethod, remoteLogoutMethod, resultsGetMethod, secretDeleteMethod, secretListMethod, secretSetMethod, shareListMethod, shareStartMethod, shareStopMethod, stateGetMethod, statePatchMethod, viewDefaultMethod, viewLaunchMethod, viewRevokeMethod, viewRotateMethod, viewUrlMethod, waitMethod } from "@mostra/protocol";
|
|
7
7
|
import { checkBrowser, checkFiles, connectControl, enclosingBundle, readBundle, readSetup, resolveRuntime } from "@mostra/sdk";
|
|
8
|
+
import { MCP_GUIDE_LINKS, MCP_PATH, createHttpEndpoint, createMcpServerFactory, defaultWorkspaceRoot, docsIndex, fileDocs, indexMarkdown, localWorkspace, nearestTopics, topicMarkdown } from "@mostra/mcp";
|
|
8
9
|
import { homedir, tmpdir } from "node:os";
|
|
9
10
|
import { randomBytes, randomUUID } from "node:crypto";
|
|
10
|
-
import { MCP_PATH, createHttpEndpoint, createMcpServerFactory, defaultWorkspaceRoot, localWorkspace } from "@mostra/mcp";
|
|
11
11
|
import { isIP } from "node:net";
|
|
12
12
|
import { serve } from "@hono/node-server";
|
|
13
13
|
import { serveStdio } from "@modelcontextprotocol/server/stdio";
|
|
@@ -30,190 +30,9 @@ function skillDir() {
|
|
|
30
30
|
const bundled = join(packageRoot(), "dist", "skill");
|
|
31
31
|
return !fromSource() && existsSync(bundled) ? bundled : join(packageRoot(), "..", "..", "skills", "mostra");
|
|
32
32
|
}
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
return
|
|
36
|
-
}
|
|
37
|
-
/** Every topic, the pages first and then the codes, sorted. */
|
|
38
|
-
function docsIndex(dir = referenceDir()) {
|
|
39
|
-
const base = DEFAULT_DOCS_BASE.replace(/\/+$/, "");
|
|
40
|
-
const pages = [];
|
|
41
|
-
for (const topic of ["cli", "telemetry"]) {
|
|
42
|
-
const file = join(dir, `${topic}.md`);
|
|
43
|
-
if (existsSync(file)) pages.push({
|
|
44
|
-
topic,
|
|
45
|
-
title: titleOf(file),
|
|
46
|
-
url: `${base}/${topic}`,
|
|
47
|
-
file
|
|
48
|
-
});
|
|
49
|
-
}
|
|
50
|
-
const errorsDir = join(dir, "errors");
|
|
51
|
-
const errors = (existsSync(errorsDir) ? readdirSync(errorsDir).filter((name) => /^MOSTRA_[A-Z0-9_]+\.md$/.test(name)).sort() : []).map((name) => {
|
|
52
|
-
const code = name.slice(0, -3);
|
|
53
|
-
const file = join(errorsDir, name);
|
|
54
|
-
return {
|
|
55
|
-
topic: code,
|
|
56
|
-
title: titleOf(file),
|
|
57
|
-
url: `${base}/errors/${code}`,
|
|
58
|
-
file
|
|
59
|
-
};
|
|
60
|
-
});
|
|
61
|
-
return [
|
|
62
|
-
...pages,
|
|
63
|
-
...guideTopics(skillDir(), base),
|
|
64
|
-
...errors
|
|
65
|
-
];
|
|
66
|
-
}
|
|
67
|
-
const byName = (a, b) => a.name < b.name ? -1 : 1;
|
|
68
|
-
/** Every file below `root`'s `prefix`, relative to `root`, sorted. */
|
|
69
|
-
function filesBelow(root, prefix) {
|
|
70
|
-
return readdirSync(join(root, prefix), { withFileTypes: true }).sort(byName).flatMap((entry) => {
|
|
71
|
-
const path = `${prefix}/${entry.name}`;
|
|
72
|
-
return entry.isDirectory() ? filesBelow(root, path) : [path];
|
|
73
|
-
});
|
|
74
|
-
}
|
|
75
|
-
/**
|
|
76
|
-
* The Skill as topics: `guide` (its SKILL.md), `guide/<name>` for each reference,
|
|
77
|
-
* `guide/<file>` for each asset (the baseline stylesheet), and `guide/examples/<name>` for each
|
|
78
|
-
* example, every file of it.
|
|
79
|
-
*/
|
|
80
|
-
function guideTopics(dir, base) {
|
|
81
|
-
const skill = join(dir, "SKILL.md");
|
|
82
|
-
if (!existsSync(skill)) return [];
|
|
83
|
-
const topics = [{
|
|
84
|
-
topic: "guide",
|
|
85
|
-
title: "Using Mostra",
|
|
86
|
-
url: `${base}/guide`,
|
|
87
|
-
file: skill
|
|
88
|
-
}];
|
|
89
|
-
const references = join(dir, "references");
|
|
90
|
-
if (existsSync(references)) for (const name of readdirSync(references).filter((entry) => entry.endsWith(".md")).sort()) {
|
|
91
|
-
const file = join(references, name);
|
|
92
|
-
const slug = name.slice(0, -3);
|
|
93
|
-
topics.push({
|
|
94
|
-
topic: `guide/${slug}`,
|
|
95
|
-
title: titleOf(file),
|
|
96
|
-
url: `${base}/guide/${slug}`,
|
|
97
|
-
file
|
|
98
|
-
});
|
|
99
|
-
}
|
|
100
|
-
const assets = join(dir, "assets");
|
|
101
|
-
if (!existsSync(assets)) return topics;
|
|
102
|
-
for (const entry of readdirSync(assets, { withFileTypes: true }).sort(byName)) {
|
|
103
|
-
if (!entry.isFile()) continue;
|
|
104
|
-
topics.push({
|
|
105
|
-
topic: `guide/${entry.name}`,
|
|
106
|
-
title: entry.name,
|
|
107
|
-
url: `${base}/guide/${entry.name}`,
|
|
108
|
-
file: join(assets, entry.name),
|
|
109
|
-
files: [entry.name]
|
|
110
|
-
});
|
|
111
|
-
}
|
|
112
|
-
const examples = join(assets, "examples");
|
|
113
|
-
if (!existsSync(examples)) return topics;
|
|
114
|
-
for (const entry of readdirSync(examples, { withFileTypes: true }).sort(byName)) {
|
|
115
|
-
if (!entry.isDirectory()) continue;
|
|
116
|
-
const files = filesBelow(assets, `examples/${entry.name}`);
|
|
117
|
-
if (files.length === 0) continue;
|
|
118
|
-
topics.push({
|
|
119
|
-
topic: `guide/examples/${entry.name}`,
|
|
120
|
-
title: `Example: ${entry.name}`,
|
|
121
|
-
url: `${base}/guide/examples/${entry.name}`,
|
|
122
|
-
file: join(assets, files[0]),
|
|
123
|
-
files
|
|
124
|
-
});
|
|
125
|
-
}
|
|
126
|
-
return topics;
|
|
127
|
-
}
|
|
128
|
-
const FENCE_LANGUAGES = {
|
|
129
|
-
".css": "css",
|
|
130
|
-
".json": "json",
|
|
131
|
-
".md": "md",
|
|
132
|
-
".mdx": "mdx",
|
|
133
|
-
".ts": "ts",
|
|
134
|
-
".tsx": "tsx"
|
|
135
|
-
};
|
|
136
|
-
/** How the guide's relative links read through the CLI, before each of its pages. */
|
|
137
|
-
const GUIDE_LINKS = "> Read through `mostra docs`: a link to `references/<name>.md` is `mostra docs guide/<name>`, `assets/<file>` is `mostra docs guide/<file>`, and `assets/examples/<name>/` is `mostra docs guide/examples/<name>`.";
|
|
138
|
-
/** The same for the guide read through `mostra mcp` (D164): topics of `docs_search`, or resources. */
|
|
139
|
-
const MCP_GUIDE_LINKS = "> Read through Mostra's MCP server: a link to `references/<name>.md` is the topic `guide/<name>`, `assets/<file>` is `guide/<file>`, and `assets/examples/<name>/` is `guide/examples/<name>`; read one with docs_search (`topic`) or the resource `mostra://docs/<topic>`. Where the guide runs a `mostra` command, use the tool of the same step (artifact_verify for `mostra verify`, artifact_wait for `mostra wait`).";
|
|
140
|
-
/**
|
|
141
|
-
* A topic's Markdown. A guide page loses its frontmatter and says how its links read (through the
|
|
142
|
-
* CLI by default, or `links`); a guide topic made of files shows each one as code under its path.
|
|
143
|
-
*/
|
|
144
|
-
function topicMarkdown(topic, dir = skillDir(), links = GUIDE_LINKS) {
|
|
145
|
-
if (topic.files !== void 0) {
|
|
146
|
-
const parts = topic.files.map((path) => {
|
|
147
|
-
const text = readFileSync(join(dir, "assets", path), "utf8");
|
|
148
|
-
const fence = text.includes("```") ? "````" : "```";
|
|
149
|
-
const body = text.endsWith("\n") ? text : `${text}\n`;
|
|
150
|
-
return `## \`${path}\`\n\n${fence}${FENCE_LANGUAGES[extname(path)] ?? ""}\n${body}${fence}\n`;
|
|
151
|
-
});
|
|
152
|
-
return [
|
|
153
|
-
`# ${topic.title}`,
|
|
154
|
-
"",
|
|
155
|
-
links,
|
|
156
|
-
"",
|
|
157
|
-
...parts
|
|
158
|
-
].join("\n");
|
|
159
|
-
}
|
|
160
|
-
const text = readFileSync(topic.file, "utf8");
|
|
161
|
-
if (topic.topic !== "guide" && !topic.topic.startsWith("guide/")) return text;
|
|
162
|
-
return [
|
|
163
|
-
links,
|
|
164
|
-
"",
|
|
165
|
-
text.replace(/^---\n[\s\S]*?\n---\n+/, "")
|
|
166
|
-
].join("\n");
|
|
167
|
-
}
|
|
168
|
-
/** The index as Markdown: what `mostra docs` prints without a topic. */
|
|
169
|
-
function indexMarkdown(topics) {
|
|
170
|
-
const pages = topics.filter((topic) => !topic.topic.startsWith("MOSTRA_") && !topic.topic.startsWith("guide"));
|
|
171
|
-
const guide = topics.filter((topic) => topic.topic === "guide" || topic.topic.startsWith("guide/"));
|
|
172
|
-
const codes = topics.filter((topic) => topic.topic.startsWith("MOSTRA_"));
|
|
173
|
-
return [
|
|
174
|
-
"# Mostra reference",
|
|
175
|
-
"",
|
|
176
|
-
"Run `mostra docs <topic>` to read one. Diagnostic codes are topics too.",
|
|
177
|
-
"",
|
|
178
|
-
...pages.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
|
|
179
|
-
"",
|
|
180
|
-
...guide.length > 0 ? [
|
|
181
|
-
"## Writing artifacts",
|
|
182
|
-
"",
|
|
183
|
-
...guide.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
|
|
184
|
-
""
|
|
185
|
-
] : [],
|
|
186
|
-
"## Diagnostic codes",
|
|
187
|
-
"",
|
|
188
|
-
...codes.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
|
|
189
|
-
""
|
|
190
|
-
].join("\n");
|
|
191
|
-
}
|
|
192
|
-
/** The topics nearest an unknown one, for its usage error. */
|
|
193
|
-
function nearestTopics(wanted, topics, count = 3) {
|
|
194
|
-
const target = wanted.toUpperCase();
|
|
195
|
-
return topics.map((topic) => {
|
|
196
|
-
const name = topic.topic.toUpperCase();
|
|
197
|
-
const contains = name.includes(target) || target.includes(name) ? 0 : 1;
|
|
198
|
-
return {
|
|
199
|
-
topic: topic.topic,
|
|
200
|
-
score: contains * 100 + distance(name, target)
|
|
201
|
-
};
|
|
202
|
-
}).sort((a, b) => a.score - b.score || (a.topic < b.topic ? -1 : 1)).slice(0, count).map((item) => item.topic);
|
|
203
|
-
}
|
|
204
|
-
/** Levenshtein distance. */
|
|
205
|
-
function distance(a, b) {
|
|
206
|
-
const row = Array.from({ length: b.length + 1 }, (_, index) => index);
|
|
207
|
-
for (let i = 1; i <= a.length; i += 1) {
|
|
208
|
-
let previous = row[0];
|
|
209
|
-
row[0] = i;
|
|
210
|
-
for (let j = 1; j <= b.length; j += 1) {
|
|
211
|
-
const current = row[j];
|
|
212
|
-
row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
|
|
213
|
-
previous = current;
|
|
214
|
-
}
|
|
215
|
-
}
|
|
216
|
-
return row[b.length];
|
|
33
|
+
/** Every topic of the reference this CLI ships, the pages first and then the codes, sorted. */
|
|
34
|
+
function docsIndex$1(dir = referenceDir()) {
|
|
35
|
+
return docsIndex(dir, skillDir());
|
|
217
36
|
}
|
|
218
37
|
//#endregion
|
|
219
38
|
//#region src/home.ts
|
|
@@ -2060,7 +1879,7 @@ const docsCommand = defineCommand({
|
|
|
2060
1879
|
local: true,
|
|
2061
1880
|
quiet: true,
|
|
2062
1881
|
async run(context) {
|
|
2063
|
-
const topics = docsIndex();
|
|
1882
|
+
const topics = docsIndex$1();
|
|
2064
1883
|
const wanted = context.args["topic"];
|
|
2065
1884
|
if (typeof wanted !== "string") {
|
|
2066
1885
|
const markdown = indexMarkdown(topics);
|
|
@@ -2080,7 +1899,7 @@ const docsCommand = defineCommand({
|
|
|
2080
1899
|
}
|
|
2081
1900
|
const found = topics.find((topic) => topic.topic === wanted || topic.topic === wanted.toUpperCase());
|
|
2082
1901
|
if (!found) throw usage(`No topic "${wanted}". The nearest: ${nearestTopics(wanted, topics).join(", ")}. Run "mostra docs" for the index.`);
|
|
2083
|
-
const markdown = topicMarkdown(found);
|
|
1902
|
+
const markdown = topicMarkdown(found, skillDir());
|
|
2084
1903
|
return {
|
|
2085
1904
|
result: {
|
|
2086
1905
|
topic: found.topic,
|
|
@@ -3472,28 +3291,11 @@ function daemonInstance(options) {
|
|
|
3472
3291
|
}
|
|
3473
3292
|
/** The bundled reference (`mostra docs`), read as the MCP server's docs. */
|
|
3474
3293
|
function bundledDocs() {
|
|
3475
|
-
|
|
3476
|
-
|
|
3477
|
-
|
|
3478
|
-
|
|
3479
|
-
};
|
|
3480
|
-
const cache = /* @__PURE__ */ new Map();
|
|
3481
|
-
return {
|
|
3482
|
-
topics: () => all().map((topic) => ({
|
|
3483
|
-
topic: topic.topic,
|
|
3484
|
-
title: topic.title,
|
|
3485
|
-
url: topic.url
|
|
3486
|
-
})),
|
|
3487
|
-
read(topic) {
|
|
3488
|
-
const cached = cache.get(topic);
|
|
3489
|
-
if (cached !== void 0) return cached;
|
|
3490
|
-
const found = all().find((entry) => entry.topic === topic);
|
|
3491
|
-
if (found === void 0) return void 0;
|
|
3492
|
-
const markdown = topicMarkdown(found, skillDir(), MCP_GUIDE_LINKS);
|
|
3493
|
-
cache.set(topic, markdown);
|
|
3494
|
-
return markdown;
|
|
3495
|
-
}
|
|
3496
|
-
};
|
|
3294
|
+
return fileDocs({
|
|
3295
|
+
referenceDir: referenceDir(),
|
|
3296
|
+
skillDir: skillDir(),
|
|
3297
|
+
links: MCP_GUIDE_LINKS
|
|
3298
|
+
});
|
|
3497
3299
|
}
|
|
3498
3300
|
/** The daemon instance, with the runtime's install started at once (D164 item 7). */
|
|
3499
3301
|
function startInstance(options) {
|
|
@@ -3758,8 +3560,9 @@ const mcpCommand = defineCommand({
|
|
|
3758
3560
|
* remote server by the OAuth device authorization grant, so `mostra share --cloud` can host its
|
|
3759
3561
|
* artifacts there, and signs out again. The instance keeps the refresh token in the home,
|
|
3760
3562
|
* owner-only; signing out keeps its instance link, so the artifacts it shared stay its own at the
|
|
3761
|
-
* next sign-in, unless `--forget`.
|
|
3762
|
-
* `remote/
|
|
3563
|
+
* next sign-in, unless `--forget`. With `--key-file`, a machine links with a key the server's
|
|
3564
|
+
* operator issued instead (`remote/link`, D167). Clients of `remote/login`, `remote/login.wait`,
|
|
3565
|
+
* `remote/link` and `remote/logout`.
|
|
3763
3566
|
*/
|
|
3764
3567
|
/** How long `mostra login` waits for the person to approve, in all (the code lives 10 minutes). */
|
|
3765
3568
|
const LOGIN_WAIT_MS = 6e5;
|
|
@@ -3778,6 +3581,10 @@ const loginCommand = defineCommand({
|
|
|
3778
3581
|
name: "default",
|
|
3779
3582
|
kind: "boolean",
|
|
3780
3583
|
summary: "Make this machine the account's default, the one chat apps create pages on. Default: the first machine linked."
|
|
3584
|
+
}, {
|
|
3585
|
+
name: "key-file",
|
|
3586
|
+
kind: "string",
|
|
3587
|
+
summary: "Link with a key the server's operator issued for an account, read from this file, instead of a person's sign-in (for an always-on machine)."
|
|
3781
3588
|
}],
|
|
3782
3589
|
output: {
|
|
3783
3590
|
type: "RemoteLoginWaitResult",
|
|
@@ -3787,6 +3594,28 @@ const loginCommand = defineCommand({
|
|
|
3787
3594
|
example: "login https://api.example.com",
|
|
3788
3595
|
async run(context) {
|
|
3789
3596
|
const server = context.args["server"];
|
|
3597
|
+
const keyFile = flag(context, "key-file");
|
|
3598
|
+
if (keyFile !== void 0) {
|
|
3599
|
+
if (typeof server !== "string") throw usage("Name the server the key is for: mostra login <server> --key-file <file>.");
|
|
3600
|
+
let key;
|
|
3601
|
+
try {
|
|
3602
|
+
key = readFileSync(resolve(context.cwd, keyFile), "utf8").trim();
|
|
3603
|
+
} catch (error) {
|
|
3604
|
+
throw usage(`--key-file ${keyFile} can't be read (${error.code ?? "error"}).`);
|
|
3605
|
+
}
|
|
3606
|
+
const linked = await context.call(remoteLinkMethod, {
|
|
3607
|
+
server: server.replace(/\/+$/, ""),
|
|
3608
|
+
key,
|
|
3609
|
+
...context.flags["default"] === true ? { default: true } : {}
|
|
3610
|
+
});
|
|
3611
|
+
return {
|
|
3612
|
+
result: {
|
|
3613
|
+
status: "signed-in",
|
|
3614
|
+
...linked
|
|
3615
|
+
},
|
|
3616
|
+
human: `Linked to ${linked.server} for ${linked.account.name ?? linked.account.id} with the operator's key. This machine is ${linked.instanceId}.\n`
|
|
3617
|
+
};
|
|
3618
|
+
}
|
|
3790
3619
|
const started = await context.call(remoteLoginMethod, {
|
|
3791
3620
|
...typeof server === "string" ? { server: server.replace(/\/+$/, "") } : {},
|
|
3792
3621
|
...context.flags["default"] === true ? { default: true } : {}
|
|
@@ -3846,6 +3675,64 @@ const logoutCommand = defineCommand({
|
|
|
3846
3675
|
};
|
|
3847
3676
|
}
|
|
3848
3677
|
});
|
|
3678
|
+
/** `mostra pause <artifact> [--reason <text>]` (D165 item 14). */
|
|
3679
|
+
const pauseCommand = defineCommand({
|
|
3680
|
+
path: ["pause"],
|
|
3681
|
+
summary: "Pause an artifact: its pages stay viewable and its links valid, but it takes no answers and runs no actions until resumed.",
|
|
3682
|
+
args: [{
|
|
3683
|
+
name: "artifact",
|
|
3684
|
+
summary: "The artifact: its source path or its ID."
|
|
3685
|
+
}],
|
|
3686
|
+
flags: [{
|
|
3687
|
+
name: "reason",
|
|
3688
|
+
kind: "string",
|
|
3689
|
+
summary: "Why, shown to the page's viewers beside the paused notice."
|
|
3690
|
+
}],
|
|
3691
|
+
output: {
|
|
3692
|
+
type: "ArtifactPauseResult",
|
|
3693
|
+
topic: "cli"
|
|
3694
|
+
},
|
|
3695
|
+
exits: [EXIT.failure, EXIT.environment],
|
|
3696
|
+
example: "pause ./survey --reason \"Closed for review until Monday\"",
|
|
3697
|
+
async run(context) {
|
|
3698
|
+
const reason = flag(context, "reason");
|
|
3699
|
+
const result = await context.call(artifactPauseMethod, {
|
|
3700
|
+
artifact: artifactRef(arg(context, "artifact"), context.cwd),
|
|
3701
|
+
paused: true,
|
|
3702
|
+
...reason !== void 0 ? { reason } : {}
|
|
3703
|
+
});
|
|
3704
|
+
return {
|
|
3705
|
+
result,
|
|
3706
|
+
human: result.by === "operator" ? "Paused. The server's operator paused it too, and only the operator resumes that.\n" : "Paused. Pages stay viewable; answers and actions wait until mostra resume.\n"
|
|
3707
|
+
};
|
|
3708
|
+
}
|
|
3709
|
+
});
|
|
3710
|
+
/** `mostra resume <artifact>` (D165 item 14). */
|
|
3711
|
+
const resumeCommand = defineCommand({
|
|
3712
|
+
path: ["resume"],
|
|
3713
|
+
summary: "Resume a paused artifact: it takes answers and runs actions again.",
|
|
3714
|
+
args: [{
|
|
3715
|
+
name: "artifact",
|
|
3716
|
+
summary: "The artifact: its source path or its ID."
|
|
3717
|
+
}],
|
|
3718
|
+
output: {
|
|
3719
|
+
type: "ArtifactPauseResult",
|
|
3720
|
+
topic: "cli"
|
|
3721
|
+
},
|
|
3722
|
+
exits: [EXIT.failure, EXIT.environment],
|
|
3723
|
+
example: "resume ./survey",
|
|
3724
|
+
async run(context) {
|
|
3725
|
+
const result = await context.call(artifactPauseMethod, {
|
|
3726
|
+
artifact: artifactRef(arg(context, "artifact"), context.cwd),
|
|
3727
|
+
paused: false
|
|
3728
|
+
});
|
|
3729
|
+
return {
|
|
3730
|
+
result,
|
|
3731
|
+
human: result.paused ? "Still paused: the server's operator paused it, and only the operator resumes that.\n" : "Resumed. The artifact takes answers and runs actions again.\n",
|
|
3732
|
+
...result.paused ? { exit: EXIT.failure } : {}
|
|
3733
|
+
};
|
|
3734
|
+
}
|
|
3735
|
+
});
|
|
3849
3736
|
//#endregion
|
|
3850
3737
|
//#region src/commands/sharing.ts
|
|
3851
3738
|
/**
|
|
@@ -4232,6 +4119,8 @@ const COMMANDS = [
|
|
|
4232
4119
|
shareListCommand,
|
|
4233
4120
|
loginCommand,
|
|
4234
4121
|
logoutCommand,
|
|
4122
|
+
pauseCommand,
|
|
4123
|
+
resumeCommand,
|
|
4235
4124
|
waitCommand,
|
|
4236
4125
|
resultsCommand,
|
|
4237
4126
|
stateGetCommand,
|
|
@@ -4699,4 +4588,4 @@ async function runRuntime(io, args, stdio) {
|
|
|
4699
4588
|
//#endregion
|
|
4700
4589
|
export { COMMANDS as a, referenceMarkdown as i, commandDefinition as n, commandHelp as r, run as t };
|
|
4701
4590
|
|
|
4702
|
-
//# sourceMappingURL=run-
|
|
4591
|
+
//# sourceMappingURL=run-BxYL-DaX.js.map
|