@hixumo/hive 0.0.0-stage → 0.0.1

package/dist/commands/sessions.js

@@ -0,0 +1,94 @@
+import { refuseServiceToken, signedIn } from "../callers.js";
+import { withConfirm } from "../device-flow.js";
+import { CliError, EXIT, plain, UsageError } from "../output.js";
+import { ago, day, inTime } from "../time.js";
+function numbered({ cli, website }) {
+    return [
+        ...cli.map((signIn, at) => ({ number: at + 1, kind: 'cli', signIn })),
+        ...website.map((signIn, at) => ({ number: cli.length + at + 1, kind: 'website', signIn })),
+    ];
+}
+export async function sessions(ctx, options) {
+    refuseServiceToken(ctx, 'hive sessions');
+    const { api } = await signedIn(ctx);
+    const list = await api.signIns();
+    const rows = numbered(list);
+    if (options.json) {
+        const of = (kind) => rows.filter((row) => row.kind === kind).map(({ number, signIn }) => ({ number, ...signIn }));
+        ctx.print(JSON.stringify({ cli: of('cli'), website: of('website') }, null, 2));
+        return EXIT.done;
+    }
+    const now = ctx.now();
+    const cli = rows.filter((row) => row.kind === 'cli');
+    const website = rows.filter((row) => row.kind === 'website');
+    const width = String(rows.length).length;
+    const section = (title, part) => [
+        `${title} (${part.length})`,
+        ...(part.length ? table(part.map((row) => [String(row.number).padStart(width), ...columnsOf(row, now)])) : ['  None.']),
+    ];
+    ctx.print([...section('CLI sign-ins', cli), '', ...section('Website sign-ins', website)].join('\n'));
+    return EXIT.done;
+}
+export async function revokeSession(ctx, options) {
+    const { ui } = ctx;
+    refuseServiceToken(ctx, 'hive sessions revoke');
+    if (!ui.interactive && !options.yes) {
+        throw new UsageError('Without a terminal to ask in, hive sessions revoke needs --yes.');
+    }
+    const { api } = await signedIn(ctx);
+    const rows = numbered(await api.signIns());
+    const target = options.target.trim();
+    const byNumber = /^\d+$/.test(target);
+    const row = rows.find((row) => (byNumber ? row.number === Number(target) : row.signIn.id === target));
+    if (!row) {
+        throw new CliError(`${byNumber ? `No sign-in numbered ${target}` : `No sign-in with the id ${plain(target)}`}. Run \`hive sessions\` to see the list.`);
+    }
+    if (row.kind === 'cli' && row.signIn.current) {
+        throw new CliError("That is this computer's own sign-in: use `hive logout` to end it.");
+    }
+    const now = ctx.now();
+    const which = row.kind === 'cli'
+        ? `the CLI sign-in ${plain(row.signIn.deviceName)} (made ${day(row.signIn.createdAt, now)}, last used ${ago(row.signIn.lastUsedAt, now)}${from(row.signIn.lastUsedIp, ', from ')})`
+        : `the website sign-in ${plain(row.signIn.device)} (started ${ago(row.signIn.createdAt, now)}${from(row.signIn.ip, ', from ')})`;
+    if (!options.yes && !(await ui.ask(`End ${which}?`, false))) {
+        ui.say('Nothing was ended.');
+        return EXIT.failed;
+    }
+    // Hive asks for "Confirm it is you" within 10 minutes before a CLI sign-in ends another one,
+    // so a stolen CLI token cannot keep its owner out.
+    const end = () => row.kind === 'cli' ? api.revokeCliSignIn(row.signIn.id) : api.endWebsiteSignIn(row.signIn.id);
+    await withConfirm(ctx, api, end, {
+        why: 'Ending a sign-in needs "Confirm it is you".',
+        noTerminal: 'Ending a sign-in needs "Confirm it is you", in a terminal. Run `hive sessions revoke` in one, or end it on the website\'s "Your sign-ins" page.',
+    });
+    ui.say(row.kind === 'cli'
+        ? `${ui.paint.green('✓')} Ended the CLI sign-in ${plain(row.signIn.deviceName)}. It is refused from its next request.`
+        : `${ui.paint.green('✓')} Ended the website sign-in ${plain(row.signIn.device)}. Its browser is sent to sign in at its next request.`);
+    return EXIT.done;
+}
+function columnsOf(row, now) {
+    if (row.kind === 'cli') {
+        const { deviceName, createdAt, lastUsedAt, lastUsedIp, current } = row.signIn;
+        return [
+            `${plain(deviceName)}${current ? ' (this computer)' : ''}`,
+            `made ${day(createdAt, now)}`,
+            `last used ${ago(lastUsedAt, now)}`,
+            from(lastUsedIp, 'from '),
+        ];
+    }
+    const { device, createdAt, expiresAt, ip, current } = row.signIn;
+    return [
+        `${plain(device)}${current ? ' (this browser)' : ''}`,
+        `started ${ago(createdAt, now)}`,
+        `ends ${inTime(expiresAt, now)}`,
+        from(ip, 'from '),
+    ];
+}
+function from(ip, prefix) {
+    return ip ? `${prefix}${plain(ip)}` : '';
+}
+/** Rows as aligned columns, two spaces apart, indented by two; no trailing spaces. */
+function table(rows) {
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    return rows.map((row) => `  ${row.map((cell, column) => cell.padEnd(widths[column])).join('  ')}`.trimEnd());
+}

package/dist/commands/whoami.js

@@ -0,0 +1,39 @@
+import { callerOf, signedIn, tokenApi } from "../callers.js";
+import { apiOrigin, writeConfig } from "../config.js";
+import { withWorkflowAccess } from "../github-actions.js";
+import { EXIT, plain } from "../output.js";
+import { day } from "../time.js";
+import { githubTarget } from "../values.js";
+/**
+ * `hive whoami`: the account signed in here; with HIVE_TOKEN, what the token reads; in GitHub
+ * Actions, the repository and what its run may read (the access it takes is ended at once): the
+ * environment from `--env`, else HIVE_ENV, else `.hive.json`, as `hive run` reads it.
+ */
+export async function whoami(ctx, options = {}) {
+    const caller = callerOf(ctx.env);
+    if (caller.kind === 'token') {
+        const info = await tokenApi(ctx, caller.token).tokenInfo();
+        ctx.print(`HIVE_TOKEN reads ${plain(info.environment.name)} of ${plain(info.project.name)}, in ${plain(info.space.name)}.`);
+        ctx.print(info.expiresAt ? `Expires ${day(info.expiresAt, ctx.now())}.` : 'Never expires.');
+        ctx.print(`Hive: ${apiOrigin(ctx.env)}`);
+        return EXIT.done;
+    }
+    if (caller.kind === 'github') {
+        const info = await withWorkflowAccess(ctx, caller.request, githubTarget(ctx, { env: options.env }), (api) => api.tokenInfo());
+        const who = info.repository ? `GitHub Actions (${plain(info.repository)})` : 'GitHub Actions';
+        ctx.print(`${who} reads ${plain(info.environment.name)} of ${plain(info.project.name)}, in ${plain(info.space.name)}.`);
+        ctx.print(`Hive: ${apiOrigin(ctx.env)}`);
+        return EXIT.done;
+    }
+    const { api, origin } = await signedIn(ctx);
+    const me = await api.me();
+    // The name may have changed at Accounts since `hive login`.
+    writeConfig(ctx.configDir, { account: { id: me.id, email: me.email, name: me.name }, apiUrl: origin });
+    ctx.print(`Signed in as ${plain(me.name)} (${plain(me.email)})`);
+    ctx.print(`Hive: ${origin}`);
+    if (me.spaces.length) {
+        const spaces = me.spaces.map(({ name, role, status }) => `${plain(name)} (${role}${status === 'paused' ? ', paused' : ''})`);
+        ctx.print(`Spaces: ${spaces.join(', ')}`);
+    }
+    return EXIT.done;
+}

package/dist/config.js

@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { apiOriginOf } from "./api-address.js";
+import { BUILT_API_URL } from "./build-info.js";
+import { ensurePrivateDir, writePrivateFile } from "./files.js";
+import { CliError } from "./output.js";
+const FOLDER = 'hixumo-hive';
+export function configDirOf(env, platform = process.platform, home = homedir()) {
+    if (env.HIVE_CONFIG_DIR)
+        return resolve(env.HIVE_CONFIG_DIR);
+    if (platform === 'win32' && env.APPDATA)
+        return join(env.APPDATA, FOLDER);
+    if (env.XDG_CONFIG_HOME)
+        return join(env.XDG_CONFIG_HOME, FOLDER);
+    return join(home, '.config', FOLDER);
+}
+export function readConfig(dir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(dir, 'config.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return {};
+    const { account, apiUrl } = parsed;
+    const config = {};
+    if (isAccount(account))
+        config.account = { id: account.id, email: account.email, name: account.name };
+    if (typeof apiUrl === 'string')
+        config.apiUrl = apiUrl;
+    return config;
+}
+function isAccount(value) {
+    const account = value;
+    return (typeof account === 'object' &&
+        account !== null &&
+        typeof account.id === 'string' &&
+        typeof account.email === 'string' &&
+        typeof account.name === 'string');
+}
+export function writeConfig(dir, config) {
+    ensurePrivateDir(dir);
+    writePrivateFile(join(dir, 'config.json'), `${JSON.stringify(config, null, 2)}\n`);
+}
+/** HIVE_API_URL when it is set, else the address this build was made for. */
+export function apiOrigin(env, built = BUILT_API_URL) {
+    const address = env.HIVE_API_URL?.trim() || built;
+    if (!address) {
+        throw new CliError("This copy of hive was built without the Hive API's address. Set HIVE_API_URL to it, like https://hive-api.example.com.");
+    }
+    try {
+        return apiOriginOf(address);
+    }
+    catch (error) {
+        throw new CliError(error.message);
+    }
+}

package/dist/context.js

@@ -0,0 +1,56 @@
+import { hostname } from 'node:os';
+import { isatty } from 'node:tty';
+import { openBrowser } from "./browser.js";
+import { askYesNo, chooseByNumber, chooseWithKeys } from "./choose.js";
+import { configDirOf } from "./config.js";
+import { credentialStore } from "./credentials.js";
+import { paintFor } from "./output.js";
+/**
+ * The terminal. Whether there is one is asked of the file descriptors, without opening
+ * process.stdin: `hive run`'s command must get the terminal untouched.
+ */
+export function terminalUi(env) {
+    const interactive = isatty(0) && isatty(2);
+    const paint = paintFor(isatty(2), env);
+    const io = () => ({ input: process.stdin, output: process.stderr });
+    return {
+        interactive,
+        paint,
+        say(text) {
+            process.stderr.write(`${text}\n`);
+        },
+        warn(text) {
+            process.stderr.write(`${paint.yellow('Warning:')} ${text}\n`);
+        },
+        ask(question, defaultYes = false) {
+            return askYesNo(io(), question, defaultYes);
+        },
+        choose(title, choices) {
+            // A terminal that cannot move the cursor gets the numbered list.
+            return env.TERM === 'dumb'
+                ? chooseByNumber(io(), title, choices)
+                : chooseWithKeys({ input: process.stdin, output: process.stderr, paint }, title, choices);
+        },
+    };
+}
+export function realContext() {
+    const env = process.env;
+    const ui = terminalUi(env);
+    const configDir = configDirOf(env);
+    return {
+        env,
+        cwd: process.cwd(),
+        ui,
+        print(text) {
+            process.stdout.write(`${text}\n`);
+        },
+        configDir,
+        credentials: credentialStore({ dir: configDir, env, warn: (text) => ui.warn(text) }),
+        // Any of the three: `hive run -- cmd > log` at a terminal still gets the terminal's Ctrl+C.
+        atTerminal: [0, 1, 2].some((fd) => isatty(fd)),
+        openBrowser,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => new Date(),
+        hostname,
+    };
+}

package/dist/credentials.js

@@ -0,0 +1,116 @@
+import { readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensurePrivateDir, writePrivateFile } from "./files.js";
+import { CliError, plain } from "./output.js";
+/**
+ * The CLI sign-in's token: in the system keychain (macOS Keychain, Windows Credential Manager,
+ * the Linux Secret Service), as `gh` keeps its own; in `credentials.json`, readable only by the
+ * person, where there is no keychain, with a warning when it is saved. HIVE_KEYRING=off skips
+ * the keychain (tests and local runs).
+ *
+ * Every token is kept with the Hive API origin it was made for, and handed out only for that
+ * origin: the keychain has one entry per origin (the account is the origin), and
+ * `credentials.json` holds `{ apiUrl, token }`. So a config folder whose config.json names
+ * another Hive, or a sign-in made from another config folder, can never carry a token anywhere
+ * but where it came from, nor replace another Hive's.
+ */
+export const KEYCHAIN_SERVICE = 'hixumo-hive';
+/**
+ * The keychain library is an optional dependency with a native part per system, which may be
+ * missing (an unusual platform, `--no-optional`): it is loaded only when needed, and its absence
+ * is the same as no keychain.
+ */
+export const openSystemKeyring = async (account) => {
+    try {
+        const keyring = await import('@napi-rs/keyring');
+        const AsyncEntry = keyring.AsyncEntry ?? keyring.default?.AsyncEntry;
+        return AsyncEntry ? new AsyncEntry(KEYCHAIN_SERVICE, account) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export function credentialStore({ dir, env, warn, openKeyring = openSystemKeyring }) {
+    const file = join(dir, 'credentials.json');
+    const keyringOff = env.HIVE_KEYRING?.trim().toLowerCase() === 'off';
+    const opened = new Map();
+    const keychain = (origin) => {
+        if (keyringOff)
+            return Promise.resolve(undefined);
+        let entry = opened.get(origin);
+        if (!entry) {
+            entry = openKeyring(origin).catch(() => undefined);
+            opened.set(origin, entry);
+        }
+        return entry;
+    };
+    return {
+        async load(origin) {
+            const entry = await keychain(origin);
+            if (entry) {
+                try {
+                    const token = await entry.getPassword();
+                    if (token)
+                        return token;
+                }
+                catch {
+                    // Locked or unreachable: the file may still hold it, from a time it could not be used.
+                }
+            }
+            const kept = readSignInFile(file);
+            return kept?.apiUrl === origin ? kept.token : undefined;
+        },
+        async save(origin, token) {
+            const kept = readSignInFile(file);
+            const entry = await keychain(origin);
+            if (entry) {
+                try {
+                    await entry.setPassword(token);
+                    // A copy of this Hive's left from a time the keychain could not be used would outlive
+                    // a logout. Another Hive's is that Hive's sign-in, and stays.
+                    if (!kept || kept.apiUrl === origin)
+                        rmSync(file, { force: true });
+                    return undefined;
+                }
+                catch {
+                    // No Secret Service on this Linux, say: the file below.
+                }
+            }
+            ensurePrivateDir(dir);
+            writePrivateFile(file, `${JSON.stringify({ apiUrl: origin, token })}\n`);
+            if (!keyringOff) {
+                warn(`No system keychain could be used here, so the sign-in is kept in ${file}, readable only by you.`);
+            }
+            return kept && kept.apiUrl !== origin ? kept : undefined;
+        },
+        async forget(origin) {
+            const entry = await keychain(origin);
+            let refusal;
+            if (entry) {
+                try {
+                    // False means there was nothing there, which is forgotten too.
+                    await entry.deletePassword();
+                }
+                catch (error) {
+                    refusal = error;
+                }
+            }
+            if (readSignInFile(file)?.apiUrl === origin)
+                rmSync(file, { force: true });
+            if (refusal !== undefined) {
+                const why = refusal instanceof Error && refusal.message ? ` (${plain(refusal.message)})` : '';
+                throw new CliError(`The system keychain did not let the sign-in be removed${why}, so it is still kept there: service ${KEYCHAIN_SERVICE}, account ${origin}. Remove it there yourself.`);
+            }
+        },
+    };
+}
+/** `credentials.json`, when it holds a token and the origin it was made for; else nothing. */
+function readSignInFile(file) {
+    try {
+        const { apiUrl, token } = JSON.parse(readFileSync(file, 'utf8'));
+        return typeof apiUrl === 'string' && apiUrl && typeof token === 'string' && token ? { apiUrl, token } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/device-flow.js

@@ -0,0 +1,93 @@
+import { ApiError } from "./api.js";
+import { CliError, plain } from "./output.js";
+/**
+ * The browser half of a device request (OAuth 2.0 device authorization, RFC 8628, as
+ * `gh auth login`): for `hive login`, and for "Confirm it is you" before a protected
+ * environment's values. The code and the address go to stderr, the browser opens on the
+ * approval page, and the CLI polls at the interval Hive gave until the person approves or
+ * denies, or the request runs out.
+ */
+const EXPIRED = 'The code ran out before it was approved. Run the command again for a new one.';
+/** Polls in a row that may fail to reach Hive (a network that dropped for a moment). */
+const UNREACHED_POLLS = 3;
+export async function approveInBrowser(ctx, start, poll, options) {
+    const { ui } = ctx;
+    const url = plain(start.verificationUrl);
+    ui.say(`Your one-time code: ${ui.paint.bold(plain(start.userCode))}`);
+    if (options.browser) {
+        ui.say(`Opening ${url} in your browser. Check the code there matches this one, then approve.`);
+        ctx.openBrowser(start.verificationUrl);
+    }
+    else {
+        ui.say(`Open ${url} in a browser, check the code there matches this one, then approve.`);
+    }
+    ui.say(ui.paint.dim('Waiting for approval (Ctrl+C to stop)…'));
+    const deadline = ctx.now().getTime() + positive(start.expiresIn, 600) * 1000;
+    let interval = positive(start.interval, 5) * 1000;
+    let unreached = 0;
+    for (;;) {
+        await ctx.sleep(interval);
+        if (ctx.now().getTime() >= deadline)
+            throw new CliError(EXPIRED);
+        try {
+            const answer = await poll(start.deviceCode);
+            unreached = 0;
+            if (answer.status !== 'pending')
+                return answer;
+        }
+        catch (error) {
+            if (!(error instanceof ApiError))
+                throw error;
+            if (error.code === 'slow_down' || error.status === 429) {
+                // RFC 8628: five seconds more, for this poll and every one after it.
+                interval += 5000;
+            }
+            else if (error.code === 'denied') {
+                throw new CliError('The request was denied in the browser.');
+            }
+            else if (error.code === 'expired' || error.status === 410 || error.status === 404) {
+                throw new CliError(EXPIRED);
+            }
+            else if (error.status === 0 && ++unreached < UNREACHED_POLLS) {
+                continue;
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+}
+/**
+ * A call Hive refuses with 403 `reauth_required` until this sign-in has confirmed it is the
+ * person within the last 10 minutes: reading a protected environment, and ending a sign-in (so a
+ * stolen CLI token cannot keep its owner out). The CLI asks for a confirm request, the person
+ * approves it in the browser, and the call is tried once more.
+ */
+export async function withConfirm(ctx, api, call, words) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        if (!needsConfirm(error))
+            throw error;
+    }
+    if (!ctx.ui.interactive)
+        throw new CliError(words.noTerminal);
+    ctx.ui.say(`${words.why} Confirm it's you in the browser.`);
+    const start = await api.startConfirm();
+    await approveInBrowser(ctx, start, (deviceCode) => api.pollConfirm(deviceCode), { browser: true });
+    try {
+        return await call();
+    }
+    catch (error) {
+        if (needsConfirm(error))
+            throw new CliError("Hive still asks to confirm it's you. Run the command again.");
+        throw error;
+    }
+}
+function needsConfirm(error) {
+    return error instanceof ApiError && error.code === 'reauth_required';
+}
+function positive(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}

package/dist/dotenv.js

@@ -0,0 +1,51 @@
+/**
+ * The `.env` text `hive pull` writes: one line per key, in the order Hive sends them (the
+ * environment's own order: its .env's order as uploaded or edited), each value written so dotenv
+ * reads it back exactly. The same rules as the website's "Copy as .env" (hixumo-hive-backend's
+ * `writeDotenv` in src/modules/variables/dotenv-text.ts), so both give the same file; the tests
+ * read every kind of value back with dotenv's own parse.
+ *
+ * dotenv turns only `\n` and `\r` back into line breaks, and only inside double quotes; it never
+ * unescapes `\\` or `\"`. It reads a backslash just before a closing quote as escaping it, so no
+ * quoted value here ever ends in one. A value goes, in this order:
+ *  - bare, when dotenv reads it back exactly and it holds no white space;
+ *  - in double quotes, line breaks as `\n`, when it holds no `"` and no `\n` or `\r` of its own;
+ *  - in single quotes, then backticks, as it is, when it holds no such quote and no carriage
+ *    return (which dotenv would turn into a line break);
+ *  - bare, when dotenv reads it back exactly (a space inside and a backslash at the end);
+ *  - escaped on one line, as most other readers expect, for what no dotenv line can hold
+ *    exactly; ending in a backslash, it gets a space before its closing quote.
+ */
+/** What dotenv reads back unchanged without quotes. */
+const READS_BARE = /^(?![\s"'`])[^#\n\r\u2028\u2029]*(?<!\s)$/;
+export function writeDotenv(values) {
+    // Hive's order, as the API's answer lists them (object keys keep their order: a key can't be
+    // a number, which is the only kind JavaScript would move).
+    return Object.keys(values)
+        .map((key) => `${key}=${quoted(values[key])}\n`)
+        .join('');
+}
+function quoted(value) {
+    const endsInBackslash = value.endsWith('\\');
+    if (READS_BARE.test(value) && !/\s/.test(value)) {
+        return value;
+    }
+    if (!value.includes('"') && !/\\[nr]/.test(value) && !endsInBackslash) {
+        return `"${escapeLineBreaks(value)}"`;
+    }
+    if (!value.includes('\r') && !endsInBackslash) {
+        for (const quote of ["'", '`']) {
+            if (!value.includes(quote)) {
+                return `${quote}${value}${quote}`;
+            }
+        }
+    }
+    if (READS_BARE.test(value)) {
+        return value;
+    }
+    const escaped = escapeLineBreaks(value.replace(/\\/g, '\\\\').replace(/"/g, '\\"'));
+    return `"${escaped}${endsInBackslash ? ' ' : ''}"`;
+}
+function escapeLineBreaks(value) {
+    return value.replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+}

package/dist/environments.js

@@ -0,0 +1,40 @@
+import { ApiError } from "./api.js";
+import { CliError, plain } from "./output.js";
+/** A project and its environments as the person sees them, for `link`, `run` and `pull`. */
+/** Environment names are unique ignoring case, so `--env Production` finds `production`. */
+export function sameName(a, b) {
+    return a.toLowerCase() === b.toLowerCase();
+}
+/** The project, or a sentence that says it is not there for this person (`where` names the id's source). */
+export async function projectOf(api, projectId, where) {
+    try {
+        return await api.project(projectId);
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 404) {
+            throw new CliError(`The project in ${where} was not found, or you don't have access to it. Run \`hive link\` to pick one.`);
+        }
+        throw error;
+    }
+}
+export function environmentNamed(project, name) {
+    const found = project.environments.find((environment) => sameName(environment.name, name));
+    if (!found) {
+        const names = project.environments.map((environment) => plain(environment.name)).join(', ');
+        throw new CliError(`No environment named ${plain(name)} in ${plain(project.name)}. Its environments: ${names}.`);
+    }
+    return found;
+}
+/** `read` and `write` show values; `names` shows keys only. */
+export function mayRead(environment) {
+    return environment.level === 'read' || environment.level === 'write';
+}
+export function assertReadable(project, environment) {
+    const where = `${plain(environment.name)} of ${plain(project.name)}`;
+    if (environment.level === 'none') {
+        throw new CliError(`You don't have access to ${where}. Ask the space's Owner or an Admin.`);
+    }
+    if (!mayRead(environment)) {
+        throw new CliError(`You can only see the names in ${where}, not the values. Ask the space's Owner or an Admin for read access.`);
+    }
+}

package/dist/files.js

@@ -0,0 +1,28 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+/** A folder only its owner can open (made so; one that is already there is left as it is). */
+export function ensurePrivateDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+/**
+ * Writes a file readable only by its owner (0600), whole or not at all: a new file next to it,
+ * then renamed over it. Writing in place would keep the mode of a file that was already there,
+ * and a stopped write would leave half a file of secrets.
+ */
+export function writePrivateFile(path, text) {
+    const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`);
+    try {
+        writeFileSync(temporary, text, { mode: 0o600, flag: 'wx' });
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+/** The error's code (`ENOENT`), for a sentence; never its message, which may quote what was read. */
+export function codeOf(error) {
+    const code = error?.code;
+    return typeof code === 'string' ? code : 'unknown error';
+}