@haakco/hostingctl 1.0.573 → 1.0.659
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/README.md +78 -21
- package/bin/hostingctl.js +13 -34
- package/bin/platforms.d.ts +24 -0
- package/bin/platforms.js +12 -15
- package/dist/main.js +6671 -1438
- package/dist/main.js.map +1 -1
- package/package.json +2 -8
- package/platform/darwin-arm64/hostingctl +0 -0
- package/platform/darwin-x64/hostingctl +0 -0
- package/platform/linux-arm64/hostingctl +0 -0
- package/platform/linux-x64/hostingctl +0 -0
- package/platform/windows-x64/hostingctl.exe +0 -0
package/README.md
CHANGED
|
@@ -26,33 +26,48 @@ npm i -g @haakco/hostingctl # install, once
|
|
|
26
26
|
```
|
|
27
27
|
|
|
28
28
|
Node 22 or newer runs the CLI, and nothing else — no checkout, no database, no cluster credentials. The
|
|
29
|
-
package also
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
29
|
+
package also carries a self-contained executable for each of the five platforms under `platform/<id>/`, and
|
|
30
|
+
its `bin` is a small JavaScript launcher: it runs the executable built for the machine it was installed on,
|
|
31
|
+
and falls back to the JavaScript bundle in `dist/` when that machine has none or `HOSTINGCTL_FORCE_JS=1` is
|
|
32
|
+
set. One package carrying all five is the trade — an install downloads every platform's executable, not
|
|
33
|
+
only the one it will run. `hostingctl --version` names which path answered it, either
|
|
34
|
+
`Launch path: native executable (linux-x64)` or the bundle and its reason.
|
|
35
|
+
|
|
36
|
+
### Running this checkout's CLI
|
|
37
|
+
|
|
38
|
+
`hostingctl` is cut from this repository, so a change here has to reach the command before it can be
|
|
39
|
+
tried. Link the checkout once, then rebuild after each change to `cli/src/`:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
cd cli && npm install && npm link # puts `hostingctl` on PATH, pointing at this checkout
|
|
43
|
+
npm run build # after editing: the launcher runs dist/main.js
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`npm link` installs this checkout's own launcher, so the command you get is the one you are editing.
|
|
47
|
+
The launcher runs the executable the package carries for this machine when there is one and otherwise the
|
|
48
|
+
bundle in `dist/`, which is why the rebuild is not optional — an unbuilt change simply does not exist yet.
|
|
33
49
|
|
|
34
50
|
### Which machines it runs on
|
|
35
51
|
|
|
36
|
-
|
|
37
|
-
|
|
52
|
+
Each executable is compiled for the machine it answers for, and for that machine's own baseline rather than
|
|
53
|
+
a newer one:
|
|
38
54
|
|
|
39
|
-
|
|
|
55
|
+
| Target | Runs on |
|
|
40
56
|
| --- | --- |
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
57
|
+
| `linux-x64` | 64-bit x86 Linux with glibc 2.17 or newer — CentOS 7, Debian 8, Ubuntu 16.04 and newer |
|
|
58
|
+
| `linux-arm64` | 64-bit ARM Linux with glibc 2.17 or newer |
|
|
59
|
+
| `windows-x64` | 64-bit Windows, as a native `hostingctl.exe` |
|
|
60
|
+
| `darwin-arm64` | Apple silicon macOS 11 or newer |
|
|
61
|
+
| `darwin-x64` | Intel macOS 10.12 or newer |
|
|
46
62
|
|
|
47
63
|
Those floors come from the toolchain the native payloads are built with: the Linux pair links against glibc
|
|
48
|
-
2.17 through Zig, and the two macOS floors are Rust's deployment targets for those architectures.
|
|
49
|
-
|
|
50
|
-
machine older than the floor above may run today's package and is not covered by this statement.
|
|
64
|
+
2.17 through Zig, and the two macOS floors are Rust's deployment targets for those architectures. A macOS
|
|
65
|
+
machine older than the floor above is not covered by this statement.
|
|
51
66
|
|
|
52
67
|
### Removing it
|
|
53
68
|
|
|
54
69
|
```bash
|
|
55
|
-
npm uninstall -g @haakco/hostingctl
|
|
70
|
+
npm uninstall -g @haakco/hostingctl
|
|
56
71
|
rm -rf ~/.config/hostingctl # the stored sessions; Windows: %APPDATA%\hostingctl
|
|
57
72
|
```
|
|
58
73
|
|
|
@@ -203,11 +218,12 @@ metadata and compared against it in CI. The groups, in one line each:
|
|
|
203
218
|
| Command | Covers |
|
|
204
219
|
| --- | --- |
|
|
205
220
|
| `whoami`, `environments`, `system`, `diagnostics` | The session's identity and reach, every environment in a company, what the cluster still holds, and the platform's health answer |
|
|
206
|
-
| `watch` | The same environment reads as a screen that refreshes itself. It ships in the Rust build the
|
|
221
|
+
| `watch` | The same environment reads as a screen that refreshes itself. It ships in the Rust build the package's executables carry; the JavaScript bundle has no `watch` |
|
|
207
222
|
| `billing` | The issuer, the price book, the discount codes a client can redeem, a month's run, the invoices and credit notes we issued, the client's own documents, and automatic invoice collection |
|
|
208
223
|
| `purchases` | What a company was sold: the record, its size and its term |
|
|
209
224
|
| `backup-destination` | The company's own bucket that also receives its backups |
|
|
210
225
|
| `secret-connection` | An environment's connections to a customer's own secret manager |
|
|
226
|
+
| `registry-connections` | A company's container-registry connections: the account, the repository scope, one verified manifest check, credential rotation and revocation. It stores no customer image and starts no workload |
|
|
211
227
|
| `storage` | Purchased object storage: a capacity's price, the purchase, an increase or a resize at that price, which basis the bucket is billed on, the bucket's connection facts, its keys, objects and bindings, the downloads measured for a month, the ceiling that caps the overage bill, and the optional stored-byte maximum that limits growth without buying capacity |
|
|
212
228
|
| `company` | The company itself, its members and roles, its activity, its logo and favicon, and the invitation journey |
|
|
213
229
|
| `environment` | Create, read, scale, retry; profile coverage, domains and redirects, databases and exports, configuration and secrets, services, site access, shared runtime and application, tools, tuning, retention, portable export, and the release bundle |
|
|
@@ -253,11 +269,30 @@ not measured, and failed timings are null rather than zero. A fast HTTP error is
|
|
|
253
269
|
The [API contract](../docs/development/api_features.md#on-demand-application-speed-check) owns the
|
|
254
270
|
bounds and interpretation. MacNan owns scheduled, multi-day and deeper monitoring.
|
|
255
271
|
|
|
272
|
+
## One command from a document to a serving environment
|
|
273
|
+
|
|
274
|
+
`environment setup` is the whole journey in one invocation: it creates or adopts the environment, applies your
|
|
275
|
+
`hosting.yaml`, sends each application's source, builds it, deploys the release and follows the environment until
|
|
276
|
+
the platform reports it ready.
|
|
277
|
+
|
|
278
|
+
```sh
|
|
279
|
+
hostingctl environment setup --company acme --name production --file hosting.yaml \
|
|
280
|
+
--source-dir . --confirm
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
`--source-dir` packages the checkout's committed `HEAD` with `git archive` — uncommitted work is not sent, and the
|
|
284
|
+
receipt names the commit it did send. `--source-archive` sends a prepared ZIP instead. Every stage prints on stderr
|
|
285
|
+
with its elapsed time and repeats on a ten-second heartbeat while the platform is still working, so a slow build
|
|
286
|
+
never looks like a stuck command; `--json` keeps stdout to one parseable document. `--dry-run` prints the plan and
|
|
287
|
+
sends nothing, `--confirm` is required to change anything, and a failure keeps the upload, build and release it
|
|
288
|
+
obtained and names the command that reads it. The [client page](https://hosting.haak.co/docs/cli) owns the worked
|
|
289
|
+
example and the reason each step exists.
|
|
290
|
+
|
|
256
291
|
## Watching a deployment settle
|
|
257
292
|
|
|
258
293
|
`hostingctl watch [uuid…]` draws a read-only screen of every environment in the company, or of just the
|
|
259
|
-
UUIDs you name, and reads again every five seconds. It is part of the Rust build the
|
|
260
|
-
carry; the JavaScript bundle the
|
|
294
|
+
UUIDs you name, and reads again every five seconds. It is part of the Rust build the package's executables
|
|
295
|
+
carry; the JavaScript bundle the launcher falls back to does not have it. Each row is what the API
|
|
261
296
|
last observed: the status word, the generation being applied against the generation known ready, whether
|
|
262
297
|
that pair is `live` or `queued`, how old the observation is, and the API's own message.
|
|
263
298
|
|
|
@@ -574,10 +609,23 @@ hyphens that start and end with a letter or digit is refused before any request.
|
|
|
574
609
|
catalog's keys and defaults to its first; a key the catalog does not offer is refused before anything is
|
|
575
610
|
sent.
|
|
576
611
|
|
|
612
|
+
`--company` is a company this account belongs to, and it creates through that company's own route.
|
|
613
|
+
`--client` is a client this account does **not** belong to: platform staff founding somebody else's first
|
|
614
|
+
environment use it, and it creates through the API's platform route, which is guarded by the platform
|
|
615
|
+
clients grant. The two are mutually exclusive — pass one or the other, and the command refuses both or
|
|
616
|
+
neither by naming the two forms. The CLI does not decide a role for itself and never falls back to the
|
|
617
|
+
company route for a client: an API permission refusal is reported as it came.
|
|
618
|
+
|
|
619
|
+
```text
|
|
620
|
+
hostingctl environment create --client acme --name "Acme Shop" --dry-run
|
|
621
|
+
hostingctl environment create --client acme --name "Acme Shop" --slug acme-shop --package small_sites --confirm
|
|
622
|
+
```
|
|
623
|
+
|
|
577
624
|
The write needs `--confirm`; `--dry-run` describes it, reads the catalog so the package it names is the one
|
|
578
625
|
the API sells, and sends nothing. The accepted answer is recorded desired state rather than a ready
|
|
579
626
|
environment: reconciliation applies it afterwards, and `--json` carries the API's own created environment
|
|
580
|
-
object.
|
|
627
|
+
object. The description, under `--json` too, names the route that ran and whose company the environment
|
|
628
|
+
landed in, so a create for a client cannot read as one for the operator's own company.
|
|
581
629
|
|
|
582
630
|
## Environment databases
|
|
583
631
|
|
|
@@ -635,6 +683,7 @@ hostingctl environment configuration show <environment-uuid> --company acme
|
|
|
635
683
|
hostingctl environment configuration preview <environment-uuid> --company acme --file acme.yaml
|
|
636
684
|
hostingctl environment configuration save <environment-uuid> --company acme --file acme.yaml --confirm
|
|
637
685
|
hostingctl environment configuration apply <environment-uuid> --company acme --file acme.yaml --confirm
|
|
686
|
+
hostingctl environment configuration apply <environment-uuid> --company acme --file acme.yaml --confirm --wait
|
|
638
687
|
hostingctl environment configuration apply <environment-uuid> --company acme --file acme.yaml \
|
|
639
688
|
--application-uuid <existing-workload-uuid> --confirm
|
|
640
689
|
hostingctl environment secret write <environment-uuid> --company acme \
|
|
@@ -649,7 +698,15 @@ hostingctl environment secret local <environment-uuid> --company acme --out .env
|
|
|
649
698
|
value. `preview` classifies the document and writes nothing; `--apply` reviews it as an apply so the verdict
|
|
650
699
|
is the one an apply relies on. `save` records a **draft** revision (not applied); `apply` records it and queues
|
|
651
700
|
normal reconciliation. Both re-run the review to obtain the hash and generation the API requires, so a
|
|
652
|
-
document that changed since review is refused rather than applied against state nobody saw.
|
|
701
|
+
document that changed since review is refused rather than applied against state nobody saw. `apply --wait`
|
|
702
|
+
then follows the environment until the generation it queued is the one applied, and reports the status word,
|
|
703
|
+
the generation and the platform's own message — the same facts the panel shows. A generation the platform
|
|
704
|
+
reports as failed stops the wait with that message; a dry run sends nothing and waits for nothing.
|
|
705
|
+
|
|
706
|
+
A document may also declare the platform bucket its environment uses (`buckets:` from schema `1.19`), with
|
|
707
|
+
the whole GiB assigned out of the storage the package already includes. The apply founds that bucket, funds
|
|
708
|
+
it and binds it before the applications are created, so the `{storage: …}` references resolve it; the
|
|
709
|
+
reviewed sentence says so before anything is sent.
|
|
653
710
|
For a document with one application, `--application-uuid` explicitly adopts an existing workload in that
|
|
654
711
|
environment. The same UUID is sent in preview and save so the reviewed hash covers the intended adoption.
|
|
655
712
|
|
package/bin/hostingctl.js
CHANGED
|
@@ -2,60 +2,40 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* The published `hostingctl` command.
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
5
|
+
* The package carries one self-contained executable per platform under `platform/<id>/`, and this
|
|
6
|
+
* launcher runs the one that matches the machine it was installed on. The JavaScript bundle in `dist/`
|
|
7
|
+
* is the fallback for a platform with no published executable, so an install always produces a working
|
|
8
|
+
* command.
|
|
9
9
|
*
|
|
10
10
|
* The launcher adds no output of its own and interprets no flags of its own: the command it runs
|
|
11
11
|
* answers, and its exit status is the command's own 0, 1 or 2.
|
|
12
12
|
*/
|
|
13
13
|
import { spawnSync } from "node:child_process";
|
|
14
14
|
import { existsSync } from "node:fs";
|
|
15
|
-
import { createRequire } from "node:module";
|
|
16
15
|
import { constants as osConstants } from "node:os";
|
|
17
16
|
import { dirname, join } from "node:path";
|
|
18
17
|
import { fileURLToPath } from "node:url";
|
|
19
18
|
import { targets } from "./platforms.js";
|
|
20
19
|
|
|
21
20
|
const here = dirname(fileURLToPath(import.meta.url));
|
|
22
|
-
const require = createRequire(import.meta.url);
|
|
23
21
|
const argv = process.argv.slice(2);
|
|
24
22
|
|
|
25
|
-
/**
|
|
26
|
-
* This launcher's own path, which is the installation the command belongs to.
|
|
27
|
-
*
|
|
28
|
-
* A native-backed install runs the platform package's executable, so the path that executable sees is the
|
|
29
|
-
* **platform package's** — and detection would then read the copy as `@haakco/hostingctl-linux-x64` and
|
|
30
|
-
* update *that*, leaving the parent the client installed untouched. Handing the launcher's own path down as
|
|
31
|
-
* `HOSTINGCTL_ENTRY` keeps the identity of the package the client actually installed, for both the native
|
|
32
|
-
* and the bundle path. A platform package run on its own has no launcher, so it keeps its own identity.
|
|
33
|
-
*/
|
|
34
|
-
const launcher = fileURLToPath(import.meta.url);
|
|
35
|
-
|
|
36
|
-
/** The platform package for this machine, or undefined when this platform has no published binary. */
|
|
23
|
+
/** The target for this machine, or undefined when this platform has no published executable. */
|
|
37
24
|
function targetFor(platform, arch) {
|
|
38
25
|
return targets.find((one) => one.platform === platform && one.arch === arch);
|
|
39
26
|
}
|
|
40
27
|
|
|
41
28
|
/**
|
|
42
|
-
* The executable
|
|
29
|
+
* The executable this machine's target carries, when the package has one for it.
|
|
43
30
|
*
|
|
44
|
-
* The
|
|
45
|
-
* install, a local install and an `npx` cache all find the same
|
|
46
|
-
*
|
|
31
|
+
* The path is resolved from the launcher's own directory rather than from `process.argv`, so a global
|
|
32
|
+
* install, a local install and an `npx` cache all find the same file. A package without the executable
|
|
33
|
+
* is not a binary: the caller falls back to the JavaScript bundle.
|
|
47
34
|
*/
|
|
48
35
|
function binaryFor(target) {
|
|
49
36
|
if (target === undefined) return undefined;
|
|
50
37
|
|
|
51
|
-
|
|
52
|
-
try {
|
|
53
|
-
manifest = require.resolve(`${target.package}/package.json`);
|
|
54
|
-
} catch {
|
|
55
|
-
return undefined;
|
|
56
|
-
}
|
|
57
|
-
|
|
58
|
-
const binary = join(dirname(manifest), target.executable);
|
|
38
|
+
const binary = join(here, "..", "platform", target.id, target.executable);
|
|
59
39
|
return existsSync(binary) ? binary : undefined;
|
|
60
40
|
}
|
|
61
41
|
|
|
@@ -85,7 +65,6 @@ function run(command, args, capture) {
|
|
|
85
65
|
const result = spawnSync(command, args, {
|
|
86
66
|
stdio: capture ? ["inherit", "pipe", "inherit"] : "inherit",
|
|
87
67
|
encoding: "utf8",
|
|
88
|
-
env: { ...process.env, HOSTINGCTL_ENTRY: launcher },
|
|
89
68
|
});
|
|
90
69
|
|
|
91
70
|
if (capture && typeof result.stdout === "string" && result.stdout !== "") {
|
|
@@ -110,7 +89,7 @@ if (!forced) {
|
|
|
110
89
|
const binary = binaryFor(target);
|
|
111
90
|
if (binary !== undefined) {
|
|
112
91
|
result = run(binary, argv, reportsPath);
|
|
113
|
-
path = `native
|
|
92
|
+
path = `native executable (${target.id})`;
|
|
114
93
|
if (result.error !== undefined) {
|
|
115
94
|
process.stderr.write(
|
|
116
95
|
`hostingctl: the published binary could not be run (${result.error.message}); using the JavaScript bundle.\n`,
|
|
@@ -123,7 +102,7 @@ if (!forced) {
|
|
|
123
102
|
if (result === undefined) {
|
|
124
103
|
if (!existsSync(bundle)) {
|
|
125
104
|
process.stderr.write(
|
|
126
|
-
"hostingctl: this installation carries neither a native
|
|
105
|
+
"hostingctl: this installation carries neither a native executable nor the JavaScript bundle.\n",
|
|
127
106
|
);
|
|
128
107
|
process.exitCode = 2;
|
|
129
108
|
} else {
|
|
@@ -131,7 +110,7 @@ if (result === undefined) {
|
|
|
131
110
|
path =
|
|
132
111
|
forced === true
|
|
133
112
|
? "JavaScript bundle (HOSTINGCTL_FORCE_JS=1)"
|
|
134
|
-
: `JavaScript bundle (no published
|
|
113
|
+
: `JavaScript bundle (no published executable for ${process.platform}-${process.arch})`;
|
|
135
114
|
}
|
|
136
115
|
}
|
|
137
116
|
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The shape of `bin/platforms.js`, which is plain JavaScript because the launcher runs it as published.
|
|
3
|
+
*
|
|
4
|
+
* The table is the one owner of the five target names; this declaration is what lets the TypeScript side
|
|
5
|
+
* read it without a second copy of the names.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
export type Target = {
|
|
9
|
+
readonly id: string;
|
|
10
|
+
readonly platform: string;
|
|
11
|
+
readonly arch: string;
|
|
12
|
+
readonly executable: string;
|
|
13
|
+
};
|
|
14
|
+
|
|
15
|
+
export declare const targets: readonly Target[];
|
|
16
|
+
|
|
17
|
+
export declare const packageFields: {
|
|
18
|
+
readonly license: string;
|
|
19
|
+
readonly homepage: string;
|
|
20
|
+
readonly bugs: { readonly url: string };
|
|
21
|
+
readonly author: { readonly name: string; readonly url: string };
|
|
22
|
+
readonly publishConfig: { readonly access: string; readonly registry: string };
|
|
23
|
+
readonly repository: { readonly type: string; readonly url: string };
|
|
24
|
+
};
|
package/bin/platforms.js
CHANGED
|
@@ -1,46 +1,45 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The published
|
|
2
|
+
* The platforms the published package carries a binary for, and the machine each one answers for.
|
|
3
3
|
*
|
|
4
|
-
* This table is the one owner of the five
|
|
5
|
-
*
|
|
6
|
-
* refuses a manifest or
|
|
7
|
-
*
|
|
4
|
+
* This table is the one owner of the five target names. The launcher resolves this machine's executable
|
|
5
|
+
* under `platform/<id>/`, `scripts/ci/build-cli-binaries.sh` compiles and stages them into that layout,
|
|
6
|
+
* and its `check` mode refuses a manifest or a target this table does not name. A rename therefore
|
|
7
|
+
* happens here and nowhere else.
|
|
8
|
+
*
|
|
9
|
+
* One package carries all five executables rather than one package per platform, so one release is one
|
|
10
|
+
* publication on the registry. The cost is stated in the install story: an install downloads every
|
|
11
|
+
* machine's executable, not only its own.
|
|
8
12
|
*
|
|
9
13
|
* `id` is the target's name in this repository and in a release. `platform` and `arch` are Node's own
|
|
10
|
-
* values for the machine the
|
|
14
|
+
* values for the machine the executable answers for, and are what the launcher matches on.
|
|
11
15
|
*/
|
|
12
16
|
export const targets = [
|
|
13
17
|
{
|
|
14
18
|
id: "darwin-arm64",
|
|
15
|
-
package: "@haakco/hostingctl-darwin-arm64",
|
|
16
19
|
platform: "darwin",
|
|
17
20
|
arch: "arm64",
|
|
18
21
|
executable: "hostingctl",
|
|
19
22
|
},
|
|
20
23
|
{
|
|
21
24
|
id: "darwin-x64",
|
|
22
|
-
package: "@haakco/hostingctl-darwin-x64",
|
|
23
25
|
platform: "darwin",
|
|
24
26
|
arch: "x64",
|
|
25
27
|
executable: "hostingctl",
|
|
26
28
|
},
|
|
27
29
|
{
|
|
28
30
|
id: "linux-arm64",
|
|
29
|
-
package: "@haakco/hostingctl-linux-arm64",
|
|
30
31
|
platform: "linux",
|
|
31
32
|
arch: "arm64",
|
|
32
33
|
executable: "hostingctl",
|
|
33
34
|
},
|
|
34
35
|
{
|
|
35
36
|
id: "linux-x64",
|
|
36
|
-
package: "@haakco/hostingctl-linux-x64",
|
|
37
37
|
platform: "linux",
|
|
38
38
|
arch: "x64",
|
|
39
39
|
executable: "hostingctl",
|
|
40
40
|
},
|
|
41
41
|
{
|
|
42
42
|
id: "windows-x64",
|
|
43
|
-
package: "@haakco/hostingctl-windows-x64",
|
|
44
43
|
platform: "win32",
|
|
45
44
|
arch: "x64",
|
|
46
45
|
executable: "hostingctl.exe",
|
|
@@ -48,11 +47,9 @@ export const targets = [
|
|
|
48
47
|
];
|
|
49
48
|
|
|
50
49
|
/**
|
|
51
|
-
* The metadata
|
|
50
|
+
* The metadata the published package carries, apart from its own name and version.
|
|
52
51
|
*
|
|
53
|
-
* The
|
|
54
|
-
* set of answers: the same licence, the same repository, the same documentation site. The distribution
|
|
55
|
-
* check compares the main package's own fields with these, so the two cannot drift apart.
|
|
52
|
+
* The distribution check compares the committed manifest with these fields, so the two cannot drift apart.
|
|
56
53
|
*/
|
|
57
54
|
export const packageFields = {
|
|
58
55
|
license: "UNLICENSED",
|