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.

3.5 KB
Raw Blame
#!/usr/bin/env node
// Writes docs/CLI.md from `bin/mso --help`. The help text lives in ONE place (the
// comment header of bin/mso, which the CLI prints verbatim), so the doc cannot
// drift from the tool. Run after changing the header:
//
//   node scripts/gen-cli-docs.mjs          # write
//   node scripts/gen-cli-docs.mjs --check  # exit 1 if stale (used by a test)
import { execFileSync } from "node:child_process";
import { readFileSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";

const root = join(dirname(fileURLToPath(import.meta.url)), "..");
const out = join(root, "docs/CLI.md");

// MSO_ENV=/dev/null: the help must never depend on a machine's secrets file.
const help = execFileSync(join(root, "bin/mso"), ["--help"], {
  encoding: "utf8",
  env: { ...process.env, MSO_ENV: "/dev/null" },
}).trimEnd();

const doc = `<!-- GENERATED by scripts/gen-cli-docs.mjs — edit the header of bin/mso, not this file. -->

# MSO CLI

The browser UI at your instance's domain is one frontend, not the product. \`mso\`
reaches the same \`/api\` surface from a shell, so every feature is scriptable.

\`scripts/install.sh\` verifies and launches \`scripts/install-core.sh\`, which symlinks \`bin/mso\` to \`~/.local/bin/mso\`. To install it by
hand from a checkout:

\`\`\`bash
ln -s "$PWD/bin/mso" ~/.local/bin/mso
eval "$(mso completion bash)"   # optional: tab completion
\`\`\`

## First run

\`\`\`bash
mso doctor          # deps, HTTPS/login origin, service, session, device — names what broke
mso doctor --fix    # safe local repairs; never changes DNS/TLS/firewall/credentials
mso device pending  # after a browser tries to log in, approve it from here
\`\`\`

The CLI signs in with \`OS_LOGIN_PASSWORD\` from your \`.env.local\` and its own
device id (\`~/.mso/cli.device.id\`), which you approve once:

\`\`\`bash
mso device approve "$(cat ~/.mso/cli.device.id)" "mso cli"
\`\`\`

Browser sign-in must use **HTTPS**, except for loopback development/access such as
\`http://localhost:4005\`. Plain \`http://<server-ip>:4005\` may answer health/API requests,
but the browser cannot retain MSO's \`Secure\` session cookie there. Pair the device on its final
HTTPS/localhost origin; \`mso doctor\` reports this explicitly.

Device and service commands work even while the service is down — that is on
purpose, because those are exactly the commands you need when it is.

## Reference

\`\`\`
${help}
\`\`\`

## Notes

- **Every non-browser caller must send \`Origin: <base>\`.** \`proxy.ts\` blocks
  mutating \`/api\` requests that cannot prove same-origin; a browser proves it with
  \`Sec-Fetch-Site\`, and the documented fallback is an \`Origin\` whose host matches
  \`Host\`. \`mso\` does this for you. Without it, login itself returns 403
  \`cross_origin_blocked\` — before any device check — which looks like an approval
  problem and is not.
- \`--base\` targets another instance; the cookie jar is keyed by base, so switching
  never reuses a session minted for a different origin.
- \`raw\`, \`zip\` and \`term stream\` stream to stdout — redirect them to a file.
`;

if (process.argv.includes("--check")) {
  const current = (() => {
    try {
      return readFileSync(out, "utf8");
    } catch {
      return "";
    }
  })();
  if (current !== doc) {
    console.error("docs/CLI.md is stale — run: node scripts/gen-cli-docs.mjs");
    process.exit(1);
  }
  console.log("docs/CLI.md is current");
} else {
  writeFileSync(out, doc);
  console.log(`wrote ${out}`);
}