hereya-cli 0.93.1 → 0.94.0

package/dist/commands/devenv/project/init/index.js

@@ -6,6 +6,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { getBackend } from '../../../../backend/index.js';
 import { getExecutorForWorkspace } from '../../../../executor/context.js';
+import { resolveDevenvSshHost } from '../../../../lib/devenv-wake.js';
+import { getLogPath } from '../../../../lib/log.js';
 import { setKeyFilePermissions } from '../../../../lib/ssh-utils.js';
 export default class DevenvProjectInit extends Command {
     static args = {
@@ -69,14 +71,19 @@ export default class DevenvProjectInit extends Command {
         }
         const { executor } = executor$;
         env = await executor.resolveEnvValues({ env });
-        const sshHost = env.devEnvSshHost;
         const sshPrivateKey = env.devEnvSshPrivateKey;
         const sshUser = env.devEnvSshUser;
-        const sshHostDns = env.devEnvSshHostDns;
-        if (!sshHost || !sshPrivateKey || !sshUser) {
-            this.error('devEnvSshHost, devEnvSshPrivateKey, and devEnvSshUser must be set in the workspace environment');
+        if (!sshPrivateKey || !sshUser) {
+            this.error('devEnvSshPrivateKey and devEnvSshUser must be set in the workspace environment');
+        }
+        let host;
+        try {
+            host = await resolveDevenvSshHost(env);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.error(`Failed to wake dev environment: ${message}. See ${getLogPath()} for details.`);
         }
-        const host = sshHostDns || sshHost;
         const tempKeyPath = path.join(os.tmpdir(), `hereya-ssh-${randomUUID()}`);
         try {
             await fs.writeFile(tempKeyPath, sshPrivateKey);

package/dist/commands/devenv/project/uninit/index.js

@@ -6,6 +6,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { getBackend } from '../../../../backend/index.js';
 import { getExecutorForWorkspace } from '../../../../executor/context.js';
+import { resolveDevenvSshHost } from '../../../../lib/devenv-wake.js';
+import { getLogPath } from '../../../../lib/log.js';
 import { setKeyFilePermissions } from '../../../../lib/ssh-utils.js';
 export default class DevenvProjectUninit extends Command {
     static args = {
@@ -47,14 +49,19 @@ export default class DevenvProjectUninit extends Command {
         }
         const { executor } = executor$;
         env = await executor.resolveEnvValues({ env });
-        const sshHost = env.devEnvSshHost;
         const sshPrivateKey = env.devEnvSshPrivateKey;
         const sshUser = env.devEnvSshUser;
-        const sshHostDns = env.devEnvSshHostDns;
-        if (!sshHost || !sshPrivateKey || !sshUser) {
-            this.error('devEnvSshHost, devEnvSshPrivateKey, and devEnvSshUser must be set in the workspace environment');
+        if (!sshPrivateKey || !sshUser) {
+            this.error('devEnvSshPrivateKey and devEnvSshUser must be set in the workspace environment');
+        }
+        let host;
+        try {
+            host = await resolveDevenvSshHost(env);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.error(`Failed to wake dev environment: ${message}. See ${getLogPath()} for details.`);
         }
-        const host = sshHostDns || sshHost;
         const tempKeyPath = path.join(os.tmpdir(), `hereya-ssh-${randomUUID()}`);
         try {
             await fs.writeFile(tempKeyPath, sshPrivateKey);

package/dist/commands/devenv/ssh/index.d.ts

@@ -7,7 +7,4 @@ export default class DevenvSsh extends Command {
     };
     run(): Promise<void>;
     protected spawnSsh(args: string[]): Promise<void>;
-    private fetchStatus;
-    private postWake;
-    private wakeAndPoll;
 }

package/dist/commands/devenv/ssh/index.js

@@ -1,74 +1,14 @@
 import { Command, Flags } from '@oclif/core';
-import { Listr } from 'listr2';
 import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
-import { Socket } from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { getBackend } from '../../../backend/index.js';
 import { getExecutorForWorkspace } from '../../../executor/context.js';
+import { resolveDevenvSshHost } from '../../../lib/devenv-wake.js';
 import { getLogPath } from '../../../lib/log.js';
 import { setKeyFilePermissions } from '../../../lib/ssh-utils.js';
-// Polling cadence and overall timeout for the wake broker. Overridable via env
-// vars purely to keep tests fast — the defaults are the production values.
-function getWakePollIntervalMs() {
-    return Number(process.env.HEREYA_WAKE_POLL_INTERVAL_MS) || 4000;
-}
-function getWakeTimeoutMs() {
-    return Number(process.env.HEREYA_WAKE_TIMEOUT_MS) || 90_000;
-}
-// Probe budget for waiting on sshd after the EC2 instance reports running.
-// EC2 returns state=running before sshd starts accepting connections; without
-// this probe, the immediate `ssh` spawn races and gets ECONNREFUSED.
-// Set HEREYA_SSH_READY_TIMEOUT_MS=0 to disable the probe entirely (tests).
-function getSshReadyTimeoutMs() {
-    const raw = process.env.HEREYA_SSH_READY_TIMEOUT_MS;
-    if (raw === undefined)
-        return 60_000;
-    return Number(raw);
-}
-function getSshReadyAttemptIntervalMs() {
-    return Number(process.env.HEREYA_SSH_READY_ATTEMPT_INTERVAL_MS) || 2000;
-}
-function sleep(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
-    });
-}
-function probeTcp(host, port, timeoutMs) {
-    return new Promise((resolve) => {
-        const socket = new Socket();
-        let done = false;
-        const finish = (ok) => {
-            if (done)
-                return;
-            done = true;
-            socket.destroy();
-            resolve(ok);
-        };
-        socket.setTimeout(timeoutMs);
-        socket.once('connect', () => finish(true));
-        socket.once('timeout', () => finish(false));
-        socket.once('error', () => finish(false));
-        socket.connect(port, host);
-    });
-}
-async function waitForSshReady(host, port, totalTimeoutMs, attemptIntervalMs) {
-    const start = Date.now();
-    // First attempt fires immediately.
-    while (Date.now() - start < totalTimeoutMs) {
-        // eslint-disable-next-line no-await-in-loop
-        const ok = await probeTcp(host, port, Math.min(2000, attemptIntervalMs));
-        if (ok)
-            return;
-        if (Date.now() - start + attemptIntervalMs >= totalTimeoutMs)
-            break;
-        // eslint-disable-next-line no-await-in-loop
-        await sleep(attemptIntervalMs);
-    }
-    throw new Error(`SSH at ${host}:${port} did not accept connections within ${totalTimeoutMs / 1000}s`);
-}
 export default class DevenvSsh extends Command {
     static description = 'SSH into a dev environment instance.';
     static examples = [
@@ -96,27 +36,19 @@ export default class DevenvSsh extends Command {
         }
         const { executor } = executor$;
         env = await executor.resolveEnvValues({ env });
-        let sshHost = env.devEnvSshHost;
         const sshPrivateKey = env.devEnvSshPrivateKey;
         const sshUser = env.devEnvSshUser;
-        const sshHostDns = env.devEnvSshHostDns;
-        const wakeUrl = env.devEnvWakeUrl;
-        const wakeToken = env.devEnvWakeToken;
-        if (!sshHost || !sshPrivateKey || !sshUser) {
-            this.error('devEnvSshHost, devEnvSshPrivateKey, and devEnvSshUser must be set in the workspace environment');
+        if (!sshPrivateKey || !sshUser) {
+            this.error('devEnvSshPrivateKey and devEnvSshUser must be set in the workspace environment');
         }
-        if (wakeUrl && wakeToken) {
-            try {
-                const wakeResult = await this.wakeAndPoll(wakeUrl, wakeToken);
-                // Override sshHost with the freshly-resolved IP from the broker
-                sshHost = wakeResult.host;
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                this.error(`Failed to wake dev environment: ${message}. See ${getLogPath()} for details.`);
-            }
+        let host;
+        try {
+            host = await resolveDevenvSshHost(env);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.error(`Failed to wake dev environment: ${message}. See ${getLogPath()} for details.`);
         }
-        const host = sshHostDns || sshHost;
         const tempKeyPath = path.join(os.tmpdir(), `hereya-ssh-${randomUUID()}`);
         try {
             await fs.writeFile(tempKeyPath, sshPrivateKey);
@@ -145,72 +77,4 @@ export default class DevenvSsh extends Command {
         }
         return Promise.resolve();
     }
-    async fetchStatus(wakeUrl, wakeToken) {
-        const response = await fetch(`${wakeUrl}/status`, {
-            headers: { Authorization: `Bearer ${wakeToken}` },
-            method: 'GET',
-        });
-        if (!response.ok) {
-            const body = await response.text().catch(() => '');
-            throw new Error(`broker /status returned ${response.status}: ${body}`);
-        }
-        return response.json();
-    }
-    async postWake(wakeUrl, wakeToken) {
-        const response = await fetch(`${wakeUrl}/wake`, {
-            headers: { Authorization: `Bearer ${wakeToken}` },
-            method: 'POST',
-        });
-        if (!response.ok) {
-            const body = await response.text().catch(() => '');
-            throw new Error(`broker /wake returned ${response.status}: ${body}`);
-        }
-        return response.json();
-    }
-    async wakeAndPoll(wakeUrl, wakeToken) {
-        const pollIntervalMs = getWakePollIntervalMs();
-        const timeoutMs = getWakeTimeoutMs();
-        const sshReadyTimeoutMs = getSshReadyTimeoutMs();
-        const sshReadyAttemptIntervalMs = getSshReadyAttemptIntervalMs();
-        const task = new Listr([
-            {
-                task: async (ctx) => {
-                    const initial = await this.fetchStatus(wakeUrl, wakeToken);
-                    if (initial.state === 'running' && initial.host) {
-                        ctx.host = initial.host;
-                        return;
-                    }
-                    await this.postWake(wakeUrl, wakeToken);
-                    const start = Date.now();
-                    let done = false;
-                    while (!done) {
-                        if (Date.now() - start >= timeoutMs) {
-                            throw new Error(`timed out waiting for dev environment to start after ${timeoutMs / 1000}s`);
-                        }
-                        // eslint-disable-next-line no-await-in-loop
-                        await sleep(pollIntervalMs);
-                        // eslint-disable-next-line no-await-in-loop
-                        const status = await this.fetchStatus(wakeUrl, wakeToken);
-                        if (status.state === 'running' && status.host) {
-                            ctx.host = status.host;
-                            done = true;
-                        }
-                    }
-                },
-                title: 'Waking dev environment',
-            },
-            {
-                enabled: () => sshReadyTimeoutMs > 0,
-                async task(ctx) {
-                    await waitForSshReady(ctx.host, 22, sshReadyTimeoutMs, sshReadyAttemptIntervalMs);
-                },
-                title: 'Waiting for SSH to accept connections',
-            },
-        ], { concurrent: false, ctx: { host: '' } });
-        const result = await task.run();
-        if (!result.host) {
-            throw new Error('broker did not return a host after wake');
-        }
-        return { host: result.host };
-    }
 }

package/dist/commands/init/index.js

@@ -73,7 +73,7 @@ export default class Init extends Command {
                         if (!executor$.success)
                             throw new Error(executor$.reason);
                         const userParams = arrayOfStringToObject(flags.parameter);
-                        const tokenResult = await hereyaTokenUtils.generateHereyaToken(`Template: ${args.project}`);
+                        const tokenResult = await hereyaTokenUtils.generatePersonalToken(`Template: ${args.project}`);
                         ctx.parameters = {
                             ...userParams,
                             deployWorkspace: flags['deploy-workspace'],

package/dist/lib/devenv-wake.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolve the SSH host to use for a devenv workspace.
+ *
+ * - On-demand devenvs (devEnvWakeUrl + devEnvWakeToken set): wake the instance
+ *   if it's not already running, poll the broker until it reports a public IP,
+ *   probe TCP :22 until sshd accepts connections, then return the fresh IP.
+ * - Always-on devenvs (no wake URL): return the cached devEnvSshHostDns or
+ *   devEnvSshHost from workspace env unchanged. No wake, no probe.
+ *
+ * The Listr UI ("Waking dev environment", "Waiting for SSH to accept
+ * connections") only renders on the on-demand path.
+ */
+export declare function resolveDevenvSshHost(env: Record<string, string>): Promise<string>;

package/dist/lib/devenv-wake.js

@@ -0,0 +1,153 @@
+import { Listr } from 'listr2';
+import { Socket } from 'node:net';
+// Polling cadence and overall timeout for the wake broker. Overridable via env
+// vars purely to keep tests fast — the defaults are the production values.
+function getWakePollIntervalMs() {
+    return Number(process.env.HEREYA_WAKE_POLL_INTERVAL_MS) || 4000;
+}
+function getWakeTimeoutMs() {
+    return Number(process.env.HEREYA_WAKE_TIMEOUT_MS) || 90_000;
+}
+// Probe budget for waiting on sshd after the EC2 instance reports running.
+// EC2 returns state=running before sshd starts accepting connections; without
+// this probe, the immediate ssh spawn races and gets ECONNREFUSED.
+// Set HEREYA_SSH_READY_TIMEOUT_MS=0 to disable the probe entirely (tests).
+function getSshReadyTimeoutMs() {
+    const raw = process.env.HEREYA_SSH_READY_TIMEOUT_MS;
+    if (raw === undefined)
+        return 60_000;
+    return Number(raw);
+}
+function getSshReadyAttemptIntervalMs() {
+    return Number(process.env.HEREYA_SSH_READY_ATTEMPT_INTERVAL_MS) || 2000;
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function probeTcp(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        const socket = new Socket();
+        let done = false;
+        const finish = (ok) => {
+            if (done)
+                return;
+            done = true;
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => finish(true));
+        socket.once('timeout', () => finish(false));
+        socket.once('error', () => finish(false));
+        socket.connect(port, host);
+    });
+}
+async function waitForSshReady(host, port, totalTimeoutMs, attemptIntervalMs) {
+    const start = Date.now();
+    while (Date.now() - start < totalTimeoutMs) {
+        // eslint-disable-next-line no-await-in-loop
+        const ok = await probeTcp(host, port, Math.min(2000, attemptIntervalMs));
+        if (ok)
+            return;
+        if (Date.now() - start + attemptIntervalMs >= totalTimeoutMs)
+            break;
+        // eslint-disable-next-line no-await-in-loop
+        await sleep(attemptIntervalMs);
+    }
+    throw new Error(`SSH at ${host}:${port} did not accept connections within ${totalTimeoutMs / 1000}s`);
+}
+async function fetchStatus(wakeUrl, wakeToken) {
+    const response = await fetch(`${wakeUrl}/status`, {
+        headers: { Authorization: `Bearer ${wakeToken}` },
+        method: 'GET',
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new Error(`broker /status returned ${response.status}: ${body}`);
+    }
+    return response.json();
+}
+async function postWake(wakeUrl, wakeToken) {
+    const response = await fetch(`${wakeUrl}/wake`, {
+        headers: { Authorization: `Bearer ${wakeToken}` },
+        method: 'POST',
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new Error(`broker /wake returned ${response.status}: ${body}`);
+    }
+    return response.json();
+}
+async function wakeAndProbe(wakeUrl, wakeToken) {
+    const pollIntervalMs = getWakePollIntervalMs();
+    const timeoutMs = getWakeTimeoutMs();
+    const sshReadyTimeoutMs = getSshReadyTimeoutMs();
+    const sshReadyAttemptIntervalMs = getSshReadyAttemptIntervalMs();
+    const task = new Listr([
+        {
+            async task(ctx) {
+                const initial = await fetchStatus(wakeUrl, wakeToken);
+                if (initial.state === 'running' && initial.host) {
+                    ctx.host = initial.host;
+                    return;
+                }
+                await postWake(wakeUrl, wakeToken);
+                const start = Date.now();
+                let done = false;
+                while (!done) {
+                    if (Date.now() - start >= timeoutMs) {
+                        throw new Error(`timed out waiting for dev environment to start after ${timeoutMs / 1000}s`);
+                    }
+                    // eslint-disable-next-line no-await-in-loop
+                    await sleep(pollIntervalMs);
+                    // eslint-disable-next-line no-await-in-loop
+                    const status = await fetchStatus(wakeUrl, wakeToken);
+                    if (status.state === 'running' && status.host) {
+                        ctx.host = status.host;
+                        done = true;
+                    }
+                }
+            },
+            title: 'Waking dev environment',
+        },
+        {
+            enabled: () => sshReadyTimeoutMs > 0,
+            async task(ctx) {
+                await waitForSshReady(ctx.host, 22, sshReadyTimeoutMs, sshReadyAttemptIntervalMs);
+            },
+            title: 'Waiting for SSH to accept connections',
+        },
+    ], { concurrent: false, ctx: { host: '' } });
+    const result = await task.run();
+    if (!result.host) {
+        throw new Error('broker did not return a host after wake');
+    }
+    return result.host;
+}
+/**
+ * Resolve the SSH host to use for a devenv workspace.
+ *
+ * - On-demand devenvs (devEnvWakeUrl + devEnvWakeToken set): wake the instance
+ *   if it's not already running, poll the broker until it reports a public IP,
+ *   probe TCP :22 until sshd accepts connections, then return the fresh IP.
+ * - Always-on devenvs (no wake URL): return the cached devEnvSshHostDns or
+ *   devEnvSshHost from workspace env unchanged. No wake, no probe.
+ *
+ * The Listr UI ("Waking dev environment", "Waiting for SSH to accept
+ * connections") only renders on the on-demand path.
+ */
+export async function resolveDevenvSshHost(env) {
+    const wakeUrl = env.devEnvWakeUrl;
+    const wakeToken = env.devEnvWakeToken;
+    if (wakeUrl && wakeToken) {
+        return wakeAndProbe(wakeUrl, wakeToken);
+    }
+    const cachedDns = env.devEnvSshHostDns;
+    const cachedHost = env.devEnvSshHost;
+    if (!cachedHost) {
+        throw new Error('devEnvSshHost must be set in the workspace environment');
+    }
+    return cachedDns || cachedHost;
+}

package/dist/lib/hereya-token.d.ts

@@ -1,5 +1,29 @@
 export declare const hereyaTokenUtils: {
-    generateHereyaToken(description: string): Promise<null | {
+    /**
+     * Issue a workspace/devenv-scoped Hereya token via POST /api/workspaces/:name.devenv-token.
+     *
+     * The resulting token is bound to the workspace's organisation and (optionally) carries
+     * another org member's identity via `onBehalfOfEmail`. Used by `hereya devenv install`.
+     * For non-workspace flows that just need a personal token, use `generatePersonalToken`.
+     */
+    generateHereyaToken(opts: {
+        description: string;
+        onBehalfOfEmail?: string;
+        workspace: string;
+    }): Promise<null | {
+        cloudUrl: string;
+        ownerEmail: string;
+        token: string;
+    }>;
+    /**
+     * Issue a plain personal Hereya token via POST /api/personal-tokens.
+     *
+     * Returns the token under the caller's identity, with no organisation scope.
+     * Used by template-scaffolding flows (`hereya init`) where the token is consumed
+     * before any workspace exists, and the cross-org-reach concern that motivates
+     * `generateHereyaToken` doesn't apply.
+     */
+    generatePersonalToken(description: string): Promise<null | {
         cloudUrl: string;
         token: string;
     }>;

package/dist/lib/hereya-token.js

@@ -1,6 +1,62 @@
 import { getCloudCredentials, loadBackendConfig } from '../backend/config.js';
 export const hereyaTokenUtils = {
-    async generateHereyaToken(description) {
+    /**
+     * Issue a workspace/devenv-scoped Hereya token via POST /api/workspaces/:name.devenv-token.
+     *
+     * The resulting token is bound to the workspace's organisation and (optionally) carries
+     * another org member's identity via `onBehalfOfEmail`. Used by `hereya devenv install`.
+     * For non-workspace flows that just need a personal token, use `generatePersonalToken`.
+     */
+    async generateHereyaToken(opts) {
+        const backendConfig = await loadBackendConfig();
+        if (!backendConfig.cloud) {
+            return null;
+        }
+        const { clientId, url } = backendConfig.cloud;
+        const credentials = await getCloudCredentials(clientId);
+        if (!credentials) {
+            return null;
+        }
+        const body = {
+            description: opts.description,
+            expiresInDays: 365,
+        };
+        if (opts.onBehalfOfEmail) {
+            body.targetUserEmail = opts.onBehalfOfEmail;
+        }
+        const response = await fetch(`${url}/api/workspaces/${encodeURIComponent(opts.workspace)}.devenv-token`, {
+            body: JSON.stringify(body),
+            headers: {
+                Authorization: `Bearer ${credentials.accessToken}`,
+                'Content-Type': 'application/json',
+            },
+            method: 'POST',
+        });
+        if (!response.ok) {
+            const rawBody = await response.text();
+            let serverMessage;
+            try {
+                const parsed = JSON.parse(rawBody);
+                serverMessage = parsed.message ?? parsed.error;
+            }
+            catch {
+                // Body wasn't JSON; fall through to use the raw text below.
+            }
+            const detail = serverMessage ?? rawBody.trim() ?? `HTTP ${response.status}`;
+            throw new Error(`Failed to generate Hereya token (HTTP ${response.status}): ${detail}`);
+        }
+        const result = (await response.json());
+        return { cloudUrl: url, ownerEmail: result.ownerEmail, token: result.token };
+    },
+    /**
+     * Issue a plain personal Hereya token via POST /api/personal-tokens.
+     *
+     * Returns the token under the caller's identity, with no organisation scope.
+     * Used by template-scaffolding flows (`hereya init`) where the token is consumed
+     * before any workspace exists, and the cross-org-reach concern that motivates
+     * `generateHereyaToken` doesn't apply.
+     */
+    async generatePersonalToken(description) {
         const backendConfig = await loadBackendConfig();
         if (!backendConfig.cloud) {
             return null;
@@ -23,7 +79,7 @@ export const hereyaTokenUtils = {
         if (!response.ok) {
             return null;
         }
-        const result = await response.json();
+        const result = (await response.json());
         return { cloudUrl: url, token: result.data.token };
     },
 };