@gheima/cli 0.6.0 → 0.7.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/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # @gheima/cli
2
2
 
3
+ ## 0.7.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 9067536: **`gheima run <service> -- <cmd>`** runs a one-off command (a migration, a seed) in a fresh container from the service's live image and environment, waits for it, prints its log and exits with the command's own exit code, or **9** when the run ended without one (refused, timed out). `--timeout <seconds>` (default 300, at most 3600) bounds the command; `--no-wait` only queues it. Under `--json`, stdout is one document holding the run and its log.
8
+
9
+ ### Patch Changes
10
+
11
+ - d011c04: **Breaking (types only):** response types now say what the API actually sends. `ServiceSummary.url` and `.branch`, and `Service.projectId`, `.subdomain` and `.repoBranch` are `string | null` (a service need not sit in a project, and has no URL until it is routed). `Service` no longer declares `branch`, which the single-service response never carried — use `repoBranch`. `QueueSummary.keyPrefix` is `string | null`, and `ActivityEvent` is read from the API contract: `metadata` is `unknown` (narrow it before use) and `actorName` is added. Code that compiled against 0.3.0 may need a null check; nothing changes at runtime.
12
+
13
+ `gheima open --live` now says the service has no live URL yet instead of trying to open `null`.
14
+
15
+ - Updated dependencies [d011c04]
16
+ - @gheima/sdk@0.4.0
17
+
3
18
  ## 0.6.0
4
19
 
5
20
  ### Minor Changes
package/README.md CHANGED
@@ -9,7 +9,15 @@ gheima login
9
9
  gheima services
10
10
  ```
11
11
 
12
- Requires Node.js 20.18.1 or newer.
12
+ Requires Node.js 20.18.1 or newer, unless you use the standalone binary, which needs nothing:
13
+
14
+ ```bash
15
+ curl -fsSL https://gheima.ma/install.sh | sh # macOS / Linux, checksum-verified, to ~/.local/bin
16
+ brew install gheima/tap/gheima # or Homebrew
17
+ ```
18
+
19
+ Windows: download `gheima-windows-x64.exe` from the
20
+ [latest release](https://github.com/gheima/cli/releases/latest).
13
21
 
14
22
  ## Authentication
15
23
 
@@ -67,17 +75,18 @@ This bites anyone who set a custom npm prefix to avoid `sudo` without also exten
67
75
 
68
76
  ### Services
69
77
 
70
- | Command | Description |
71
- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
72
- | `gheima services [list]` | List services |
73
- | `gheima services get <service>` | Show service detail |
74
- | `gheima services create --name <name> [--type WEB\|WORKER\|STATIC] [--repo <url>] [--project <id>]` | Create a service. Names are unique per **account**; omitting `--project` leaves the service ungrouped |
75
- | `gheima services delete <service> [-y]` | Delete a service |
76
- | `gheima link <service>` | Link the current directory to a service: commands run anywhere inside it then default to that service. Writes `.gheima/project.json` and adds `.gheima/` to `.gitignore` |
77
- | `gheima deploy [service] [--no-wait] [--timeout <min>]` | Deploy, stream the build, and exit 0 once it is live, or 8 if it fails. `--no-wait` only queues it |
78
- | `gheima logs [service] [-f] [-b] [-s <text>]` | Show or tail runtime (`-b` → build) logs |
79
- | `gheima templates [list]` | List marketplace templates |
80
- | `gheima templates deploy <templateId> <name> [--project <id>]` | Deploy a one-click template |
78
+ | Command | Description |
79
+ | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
+ | `gheima services [list]` | List services |
81
+ | `gheima services get <service>` | Show service detail |
82
+ | `gheima services create --name <name> [--type WEB\|WORKER\|STATIC] [--repo <url>] [--project <id>]` | Create a service. Names are unique per **account**; omitting `--project` leaves the service ungrouped |
83
+ | `gheima services delete <service> [-y]` | Delete a service |
84
+ | `gheima link <service>` | Link the current directory to a service: commands run anywhere inside it then default to that service. Writes `.gheima/project.json` and adds `.gheima/` to `.gitignore` |
85
+ | `gheima deploy [service] [--no-wait] [--timeout <min>]` | Deploy, stream the build, and exit 0 once it is live, or 8 if it fails. `--no-wait` only queues it |
86
+ | `gheima logs [service] [-f] [-b] [-s <text>]` | Show or tail runtime (`-b` → build) logs |
87
+ | `gheima run <service> [--timeout <s>] [--no-wait] -- <cmd>` | Run a one-off command (a migration, a seed) in a fresh container from the service's live image and environment, print its log, and exit with its exit code. The words after `--` are joined and run by the remote `/bin/sh -c`, so quote the whole command when an argument holds spaces: `gheima run web -- 'psql -c "select 1"'`. Admins only; 10 runs an hour per service |
88
+ | `gheima templates [list]` | List marketplace templates |
89
+ | `gheima templates deploy <templateId> <name> [--project <id>]` | Deploy a one-click template |
81
90
 
82
91
  ### Configuration
83
92
 
@@ -182,17 +191,18 @@ current one). The URL follows the same order: `--url` → `GHEIMA_URL` → profi
182
191
 
183
192
  Stable: a code never changes meaning.
184
193
 
185
- | Code | Meaning |
186
- | ---- | -------------------------------------------------------------------------------------------- |
187
- | 0 | Success |
188
- | 1 | Any other error (including a 5xx from the API) |
189
- | 2 | Usage: unknown flag, missing argument, or a prompt with no terminal (pass the flag it names) |
190
- | 3 | Not authenticated, or not allowed (401 / 403) |
191
- | 4 | Not found (404) |
192
- | 5 | Conflict or validation (400 / 409 / 412 / 422 / 428) |
193
- | 6 | Rate limited (429) |
194
- | 7 | Network failure or timeout (no response, 408, 504; also `deploy --timeout`) |
195
- | 8 | `gheima deploy` waited and the deployment did not go live (failed, cancelled, skipped) |
194
+ | Code | Meaning |
195
+ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
196
+ | 0 | Success |
197
+ | 1 | Any other error (including a 5xx from the API) |
198
+ | 2 | Usage: unknown flag, missing argument, or a prompt with no terminal (pass the flag it names) |
199
+ | 3 | Not authenticated, or not allowed (401 / 403) |
200
+ | 4 | Not found (404) |
201
+ | 5 | Conflict or validation (400 / 409 / 412 / 422 / 428) |
202
+ | 6 | Rate limited (429) |
203
+ | 7 | Network failure or timeout (no response, 408, 504; also `deploy --timeout`) |
204
+ | 8 | `gheima deploy` waited and the deployment did not go live (failed, cancelled, skipped) |
205
+ | 9 | `gheima run` ended without the command reporting an exit code (refused, timed out). Otherwise `run` exits with the command's own code, which can be any of these numbers: a command that exits 6 is not a rate limit, so after `run` branch on the command's codes, not this table |
196
206
 
197
207
  ## Examples
198
208
 
@@ -201,6 +211,8 @@ gheima services --json | jq '.[].url'
201
211
  gheima api services.delete '{"id":"svc_123"}' --yes # no terminal: destructive needs --yes
202
212
  gheima logs my-app -f --json | jq -r .line # NDJSON, one entry per line
203
213
  gheima link my-app && gheima deploy # later, just: gheima deploy
214
+ gheima run my-app -- npx prisma migrate deploy # exits with the migration's own code
215
+ gheima run my-app -- 'psql -c "select count(*) from users"' # quote it whole: the remote shell splits it
204
216
  gheima logs my-app -f
205
217
  gheima env set my-app DATABASE_URL=postgres://…
206
218
  gheima env set my-app STRIPE_SECRET --stdin < secret.txt # keeps the value out of shell history
package/dist/cli.js CHANGED
@@ -1054,8 +1054,82 @@ async function waitForDeployment(client, serviceId, deploymentId, timeoutMs) {
1054
1054
  stop.abort();
1055
1055
  }
1056
1056
  }
1057
- /** How often `deploy` asks for the outcome. Tests shorten it. */
1057
+ /** How often `deploy` and `run` ask for the outcome. Tests shorten it. */
1058
1058
  const POLL_MS = Number(process.env.GHEIMA_DEPLOY_POLL_MS) || 3000;
1059
+ /** Statuses a one-off run never leaves (the `CronStatus` values its row reuses). */
1060
+ const RUN_FINISHED = new Set(['SUCCESS', 'FAILED', 'SKIPPED']);
1061
+ /** How long `run` waits beyond the command's own timeout, for the run to leave the queue. */
1062
+ const RUN_QUEUE_SLACK_MS = 10 * 60_000;
1063
+ program
1064
+ .command('run <service> <command...>')
1065
+ .description("Run a one-off command against the service's live image and environment, print its log, " +
1066
+ 'and exit with its exit code. Put the command after `--`. The words are joined and run by the ' +
1067
+ 'remote /bin/sh -c, so quote the whole command when an argument holds spaces')
1068
+ .option('--timeout <seconds>', 'stop the command after this long (1-3600)', '300')
1069
+ .option('--no-wait', 'queue the run and exit without waiting for it')
1070
+ .action(async (ref, words, opts, cmd) => {
1071
+ const g = globals(cmd);
1072
+ try {
1073
+ const timeout = Number(opts.timeout);
1074
+ // Checked before anything is queued: the API would refuse it, but only after a lookup.
1075
+ if (!Number.isInteger(timeout) || timeout < 1 || timeout > 3600) {
1076
+ throw new UsageError(`--timeout must be a whole number of seconds from 1 to 3600, not ${opts.timeout}.`);
1077
+ }
1078
+ const client = makeClient(g);
1079
+ const id = await resolveServiceId(client, ref);
1080
+ // Joined as typed, like `heroku run`: the remote shell does the word splitting, so
1081
+ // `gheima run web -- 'npm run migrate && npm run seed'` means what it says.
1082
+ const { run } = (await callOp('services.createRun', { id, command: words.join(' '), timeoutSeconds: timeout }, g));
1083
+ if (!opts.wait) {
1084
+ if (g.json)
1085
+ return printJson(run);
1086
+ return success(`Run queued: ${color.bold(run.id)}`);
1087
+ }
1088
+ info(`Run ${run.id} queued. Waiting for it to finish…`);
1089
+ const final = await waitForRun(id, run.id, timeout * 1000 + RUN_QUEUE_SLACK_MS, g);
1090
+ // Written only once the run has finished, so the log comes in one piece at the end.
1091
+ const { logs } = (await callOp('services.runLogs', { id, runId: run.id }, g));
1092
+ if (g.json)
1093
+ printJson({ run: final, logs });
1094
+ else if (logs)
1095
+ writeRaw(logs.endsWith('\n') ? logs : `${logs}\n`);
1096
+ // exitCode, not exit(): a long log on a pipe must drain before the process ends.
1097
+ if (final.exitCode !== null) {
1098
+ if (!g.json && final.exitCode !== 0) {
1099
+ process.stderr.write(`${color.red('Run')} ${run.id} exited ${final.exitCode}\n`);
1100
+ }
1101
+ process.exitCode = final.exitCode;
1102
+ return;
1103
+ }
1104
+ process.stderr.write(`${color.red('Run')} ${run.id} ended ${final.status}` +
1105
+ `${final.error ? `: ${final.error}` : ''}\n`);
1106
+ process.exitCode = EXIT.runFailed;
1107
+ }
1108
+ catch (err) {
1109
+ fail(err);
1110
+ }
1111
+ });
1112
+ /** Poll a one-off run until it finishes, saying so on stderr when it starts. */
1113
+ async function waitForRun(serviceId, runId, timeoutMs, g) {
1114
+ const deadline = Date.now() + timeoutMs;
1115
+ let started = false;
1116
+ while (Date.now() < deadline) {
1117
+ const { run } = (await callOp('services.getRun', { id: serviceId, runId }, g));
1118
+ if (RUN_FINISHED.has(run.status))
1119
+ return run;
1120
+ if (!started && run.status === 'RUNNING') {
1121
+ started = true;
1122
+ info('Running…');
1123
+ }
1124
+ await new Promise((r) => setTimeout(r, POLL_MS));
1125
+ }
1126
+ throw new GheimaError({
1127
+ status: 0,
1128
+ code: 'timeout',
1129
+ message: `Run ${runId} had not finished after ${Math.round(timeoutMs / 60_000)} minutes. ` +
1130
+ `Read it later with \`gheima services get-run ${serviceId} ${runId}\`.`,
1131
+ });
1132
+ }
1059
1133
  program
1060
1134
  .command('logs [service]')
1061
1135
  .description('Show or tail service logs (the linked service by default)')
@@ -1552,14 +1626,19 @@ program
1552
1626
  ? `${base}/services/${linked.link.serviceId}`
1553
1627
  : base;
1554
1628
  if (opts.live) {
1629
+ let live = null;
1555
1630
  try {
1556
1631
  const client = makeClient(g);
1557
1632
  const service = await client.services.get(await resolveServiceId(client, resource));
1558
- url = service.url;
1633
+ live = service.url;
1559
1634
  }
1560
1635
  catch (err) {
1561
1636
  fail(err);
1562
1637
  }
1638
+ // A service with no route yet (never deployed, or a worker) has no live URL.
1639
+ if (!live)
1640
+ fail(new Error('This service has no live URL yet'));
1641
+ url = live;
1563
1642
  }
1564
1643
  if (g.json)
1565
1644
  return printJson({ url });
package/dist/exit.js CHANGED
@@ -14,6 +14,8 @@ export const EXIT = {
14
14
  network: 7,
15
15
  /** `gheima deploy` waited, and the deployment did not go live. */
16
16
  deployFailed: 8,
17
+ /** `gheima run` ended without the command reporting an exit code (refused, timed out). */
18
+ runFailed: 9,
17
19
  };
18
20
  /** The command was invoked wrongly: a missing flag, or a prompt with nobody to answer it. */
19
21
  export class UsageError extends Error {
package/dist/version.js CHANGED
@@ -1,2 +1,2 @@
1
1
  // GENERATED by scripts/write-version.mjs from package.json. Do not edit.
2
- export const VERSION = '0.6.0';
2
+ export const VERSION = '0.7.0';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gheima/cli",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Command-line interface for the Gheima platform.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -36,7 +36,7 @@
36
36
  "undici": "^7.29.0",
37
37
  "zod": "^4.4.3",
38
38
  "@gheima/contracts": "0.2.0",
39
- "@gheima/sdk": "0.3.0"
39
+ "@gheima/sdk": "0.4.0"
40
40
  },
41
41
  "devDependencies": {
42
42
  "@arethetypeswrong/cli": "^0.18.5",