@haakco/hostingctl 1.0.563 → 1.0.614

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 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 publishes a self-contained executable per platform (`@haakco/hostingctl-linux-x64` and its
30
- four siblings, `@haakco/hostingctl-linux-arm64`, `@haakco/hostingctl-darwin-arm64`,
31
- `@haakco/hostingctl-darwin-x64` and `@haakco/hostingctl-windows-x64`); that package's `bin` **is** the
32
- native binary, so a machine with no Node installs the platform package directly and needs no runtime.
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
- The platform package you install is the one compiled for that machine, and it is built for that
37
- machine's own baseline rather than a newer one:
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
- | Package | Runs on |
55
+ | Target | Runs on |
40
56
  | --- | --- |
41
- | `hostingctl-linux-x64` | 64-bit x86 Linux with glibc 2.17 or newer — CentOS 7, Debian 8, Ubuntu 16.04 and newer |
42
- | `hostingctl-linux-arm64` | 64-bit ARM Linux with glibc 2.17 or newer |
43
- | `hostingctl-windows-x64` | 64-bit Windows, as a native `hostingctl.exe` |
44
- | `hostingctl-darwin-arm64` | Apple silicon macOS 11 or newer |
45
- | `hostingctl-darwin-x64` | Intel macOS 10.12 or newer |
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. The macOS
49
- packages still carry the earlier compiled bundle until the Mac builds their native payloads, so a macOS
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 # or the platform package, if that is the one you installed
70
+ npm uninstall -g @haakco/hostingctl
56
71
  rm -rf ~/.config/hostingctl # the stored sessions; Windows: %APPDATA%\hostingctl
57
72
  ```
58
73
 
@@ -203,16 +218,17 @@ 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 platform packages carry; the JavaScript bundle has no `watch` |
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 |
211
- | `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, and the ceiling that caps the overage bill |
226
+ | `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
227
  | `company` | The company itself, its members and roles, its activity, its logo and favicon, and the invitation journey |
213
228
  | `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 |
214
229
  | `application` | Create, rename, remove; build and deploy, build logs, runs and run logs, process schedules; recovery review and confirm; the HTTP cache and path routes; source binding; site access; the WordPress import and URL repair; the administrator credential; the component's publishable anonymous key |
215
230
  | `access` | Who may reach one environment: settings, grants, SSH keys, the shared password, and the per-user view |
231
+ | `alerts` | A company's disk alerts: what is breached now, the disks the platform reads, and the rules that email members about them |
216
232
  | `site-user` | The accounts that sign in to a company's sites |
217
233
  | `keys` | The account's personal SSH keys and where each is granted |
218
234
  | `email` | The mail service, its names, mailboxes, aliases, sending holds, send-as grants, IMAP sync (including CSV), and the platform's deliverability monitoring |
@@ -255,8 +271,8 @@ bounds and interpretation. MacNan owns scheduled, multi-day and deeper monitorin
255
271
  ## Watching a deployment settle
256
272
 
257
273
  `hostingctl watch [uuid…]` draws a read-only screen of every environment in the company, or of just the
258
- UUIDs you name, and reads again every five seconds. It is part of the Rust build the platform packages
259
- carry; the JavaScript bundle the parent npm package falls back to does not have it. Each row is what the API
274
+ UUIDs you name, and reads again every five seconds. It is part of the Rust build the package's executables
275
+ carry; the JavaScript bundle the launcher falls back to does not have it. Each row is what the API
260
276
  last observed: the status word, the generation being applied against the generation known ready, whether
261
277
  that pair is `live` or `queued`, how old the observation is, and the API's own message.
262
278
 
@@ -573,10 +589,23 @@ hyphens that start and end with a letter or digit is refused before any request.
573
589
  catalog's keys and defaults to its first; a key the catalog does not offer is refused before anything is
574
590
  sent.
575
591
 
592
+ `--company` is a company this account belongs to, and it creates through that company's own route.
593
+ `--client` is a client this account does **not** belong to: platform staff founding somebody else's first
594
+ environment use it, and it creates through the API's platform route, which is guarded by the platform
595
+ clients grant. The two are mutually exclusive — pass one or the other, and the command refuses both or
596
+ neither by naming the two forms. The CLI does not decide a role for itself and never falls back to the
597
+ company route for a client: an API permission refusal is reported as it came.
598
+
599
+ ```text
600
+ hostingctl environment create --client acme --name "Acme Shop" --dry-run
601
+ hostingctl environment create --client acme --name "Acme Shop" --slug acme-shop --package small_sites --confirm
602
+ ```
603
+
576
604
  The write needs `--confirm`; `--dry-run` describes it, reads the catalog so the package it names is the one
577
605
  the API sells, and sends nothing. The accepted answer is recorded desired state rather than a ready
578
606
  environment: reconciliation applies it afterwards, and `--json` carries the API's own created environment
579
- object.
607
+ object. The description, under `--json` too, names the route that ran and whose company the environment
608
+ landed in, so a create for a client cannot read as one for the operator's own company.
580
609
 
581
610
  ## Environment databases
582
611
 
package/bin/hostingctl.js CHANGED
@@ -2,60 +2,40 @@
2
2
  /**
3
3
  * The published `hostingctl` command.
4
4
  *
5
- * npm is the delivery truck, not the product: the package carries one self-contained executable per
6
- * platform, published as its own package, and this launcher runs the one that matches the machine it was
7
- * installed on. The JavaScript bundle in `dist/` is the fallback for a platform with no published
8
- * binary, so an install always produces a working command.
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 inside this machine's platform package, when that package is installed.
29
+ * The executable this machine's target carries, when the package has one for it.
43
30
  *
44
- * The package is resolved through the launcher's own installation rather than a path guess, so a global
45
- * install, a local install and an `npx` cache all find the same package. A package that is not installed,
46
- * or one without the executable in it, is not a binary: the caller falls back to the JavaScript bundle.
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
- let manifest;
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 binary (${target.id})`;
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 binary nor the JavaScript bundle.\n",
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 binary for ${process.platform}-${process.arch})`;
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 platform packages, and the machine each one answers for.
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 platform names. The launcher resolves the package for the
5
- * machine it runs on, `scripts/ci/build-cli-binaries.sh` compiles and stages them, and its `check` mode
6
- * refuses a manifest or an optional dependency that names a package this table does not. A rename
7
- * therefore happens here and nowhere else.
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 package answers for, and are what npm's `os` and `cpu` fields need.
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 every published package carries, apart from its own name, version and target.
50
+ * The metadata the published package carries, apart from its own name and version.
52
51
  *
53
- * The main package and the five platform packages are two surfaces of one product, so they carry one
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",