@openstory/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @openstory/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The OpenStory command line: sign in, download a sequence's files, mirror your library, and share a cut. Nothing to install:
+
+```sh
+npx @openstory/cli@latest <command>
+```
+
+Keep `@latest`: npx and bunx can otherwise run a stale cached copy. The bin is `openstory`. The unscoped `openstory` package on npm is an unrelated project.
+
+## Commands
+
+```sh
+npx @openstory/cli@latest login
+npx @openstory/cli@latest pull 01JSEQUENCE --dir ./room
+npx @openstory/cli@latest sync
+npx @openstory/cli@latest share --music score.mp3 shot.mp4 board.png --audio line.wav
+```
+
+- `login` signs in with a device code: it prints a short code and opens the approval page in your browser. `pull` and `share` do the same on first use.
+- `pull <sequenceId>` downloads the current cut into `./<sequenceId>` (or `--dir`). A later run skips a file that is already there at the same version. `--history` adds every completed version, including discarded ones. `--exports` adds rendered MP4s.
+- `pull` names folders by order and title: `scenes/03-the-chase/shots/02-wide-marlowe-runs/still.png`, `cast/marlowe/looks/default/sheet.png`. A file the previous run wrote and the sequence no longer lists is removed; nothing else in the folder is touched.
+- `sync` mirrors every sequence of your organization into `~/openstory/<organization>/<sequence>/` (or `--dir`) and keeps it current until you stop it. Your sign-up organization is `personal/`. A renamed sequence renames its folder; an archived one is left alone. The folder is output only: OpenStory never reads it back. `--once` stops after the first pass. One folder mirrors one server.
+- `share …` takes the cut options of [`@openstory/stitch`](https://github.com/openstory-so/openstory/tree/main/packages/stitch#readme), uploads every file to your organization and prints `https://openstory.so/stitch/<id>`, a page anyone with the link can watch. Every still is checked for a real person; one who is needs `--portrait-rights <basis>`, the basis for using their likeness (a release reference, `self`, a contract id).
+
+Every command takes `--origin <url>` to talk to another OpenStory server.
+
+## Files
+
+- `~/.openstory/credentials.json` holds one API key per server. A `~/.openstory/stitch.json` left by stitch 0.4 is renamed to it once.
+- `~/.openstory/assets/` holds cast, location and style files once; `pull` links them into each folder. `sync` keeps its own in `<dir>/.openstory/cache`, beside `<dir>/.openstory/sync.json`, which maps each organization and sequence to its folder.
+- `~/.openstory/cli-update.json` remembers the last check for a newer version. The CLI asks npm at most once a day, prints a one-line hint on stderr, and never updates itself. No check runs under `CI` or without a terminal.
+
+If OpenStory answers that the CLI is too old, run it again with `npx @openstory/cli@latest`.
+
+## License
+
+MIT

package/bin/openstory.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli.js';
+
+await main(process.argv.slice(2));

package/dist/api.d.ts

@@ -0,0 +1,19 @@
+/** Talking to OpenStory: the version header, the 426 answer, and the error envelope. */
+/** Mirrors CLI_VERSION_HEADER on the server (src/platform/server/api-v1/cli-version.ts). */
+export declare const CLI_VERSION_HEADER = "X-OpenStory-CLI";
+export declare const CLI_VERSION: string;
+/** Every request to OpenStory carries the CLI version; a 426 becomes the update message. */
+export declare function versionedFetch(fetchFn: typeof fetch, version?: string): typeof fetch;
+/** A JSON object's fields, or none: a wrong shape reads as missing fields. */
+export declare function recordOf(value: unknown): Record<string, unknown>;
+export declare function stringOf(value: unknown, label: string): string;
+/**
+ * The error envelope's message, with each field issue a 400 carries
+ * (`details.issues`, as `path: message`), else the raw body.
+ */
+export declare function errorText(response: Response): Promise<string>;
+/** The envelope's `error.code` beside the text, for a branch that must not rest on wording. */
+export declare function errorInfo(response: Response): Promise<{
+    code: string | null;
+    text: string;
+}>;

package/dist/api.js

@@ -0,0 +1,69 @@
+/** Talking to OpenStory: the version header, the 426 answer, and the error envelope. */
+import { readFileSync } from 'node:fs';
+/** Mirrors CLI_VERSION_HEADER on the server (src/platform/server/api-v1/cli-version.ts). */
+export const CLI_VERSION_HEADER = 'X-OpenStory-CLI';
+export const CLI_VERSION = readVersion();
+function readVersion() {
+    const text = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+    const version = recordOf(JSON.parse(text)).version;
+    if (typeof version !== 'string')
+        throw new Error('package.json has no version');
+    return version;
+}
+/** Every request to OpenStory carries the CLI version; a 426 becomes the update message. */
+export function versionedFetch(fetchFn, version = CLI_VERSION) {
+    return async (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set(CLI_VERSION_HEADER, version);
+        const response = await fetchFn(input, { ...init, headers });
+        if (response.status === 426) {
+            throw new Error(`OpenStory needs a newer @openstory/cli (you have ${version}). Run npx @openstory/cli@latest. ${await errorText(response)}`.trim());
+        }
+        return response;
+    };
+}
+/** A JSON object's fields, or none: a wrong shape reads as missing fields. */
+export function recordOf(value) {
+    return typeof value === 'object' && value !== null
+        ? Object.fromEntries(Object.entries(value))
+        : {};
+}
+export function stringOf(value, label) {
+    if (typeof value === 'string')
+        return value;
+    throw new Error(`OpenStory answered without ${label}`);
+}
+/**
+ * The error envelope's message, with each field issue a 400 carries
+ * (`details.issues`, as `path: message`), else the raw body.
+ */
+export async function errorText(response) {
+    return (await errorInfo(response)).text;
+}
+/** The envelope's `error.code` beside the text, for a branch that must not rest on wording. */
+export async function errorInfo(response) {
+    const text = await response.text().catch(() => '');
+    try {
+        const parsed = recordOf(JSON.parse(text));
+        const error = recordOf(parsed.error);
+        const code = typeof error.code === 'string' ? error.code : null;
+        const message = typeof parsed.error === 'string'
+            ? parsed.error
+            : (error.message ?? parsed.message);
+        if (typeof message !== 'string')
+            return { code, text };
+        const issues = recordOf(error.details).issues;
+        if (!Array.isArray(issues))
+            return { code, text: message };
+        const lines = issues.map((issue) => {
+            const record = recordOf(issue);
+            const path = Array.isArray(record.path) ? record.path.join('.') : '';
+            const text = typeof record.message === 'string' ? record.message : '';
+            return `${path}: ${text}`;
+        });
+        return { code, text: [message, ...lines].join('\n  ') };
+    }
+    catch {
+        return { code: null, text };
+    }
+}

package/dist/assets.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Download one sequence's files into a folder.
+ *
+ * The command asks the public API for the manifest, then writes each file.
+ * A second run skips a path whose versionId is unchanged and whose file is
+ * still there, and a path the previous manifest listed but this one does not
+ * is removed. Shared cast, location, and style files are stored once in the
+ * cache directory, named from the stored url, and linked into the folder.
+ * This file does not import the app: the skip rule is copied here on purpose.
+ */
+export type DownloadAssetsOptions = {
+    sequenceId: string;
+    origin: string;
+    /** Shared files live here once; `pull` passes ~/.openstory/assets. */
+    cacheDir: string;
+    dest: string;
+    history: boolean;
+    includeExports: boolean;
+    fetch?: typeof fetch;
+    key: () => Promise<string>;
+    refresh: () => Promise<string>;
+};
+export declare function downloadSequenceAssets(options: DownloadAssetsOptions): Promise<{
+    saved: number;
+    skipped: number;
+    removed: number;
+}>;

package/dist/assets.js

@@ -0,0 +1,283 @@
+/**
+ * Download one sequence's files into a folder.
+ *
+ * The command asks the public API for the manifest, then writes each file.
+ * A second run skips a path whose versionId is unchanged and whose file is
+ * still there, and a path the previous manifest listed but this one does not
+ * is removed. Shared cast, location, and style files are stored once in the
+ * cache directory, named from the stored url, and linked into the folder.
+ * This file does not import the app: the skip rule is copied here on purpose.
+ */
+import { createHash } from 'node:crypto';
+import { once } from 'node:events';
+import { createWriteStream } from 'node:fs';
+import { copyFile, link, mkdir, readFile, realpath, rename, rm, rmdir, stat, writeFile, } from 'node:fs/promises';
+import { dirname, extname, join, sep } from 'node:path';
+export async function downloadSequenceAssets(options) {
+    const fetchFn = options.fetch ?? fetch;
+    const manifestUrl = new URL(`/api/v1/sequences/${encodeURIComponent(options.sequenceId)}/assets`, options.origin);
+    manifestUrl.searchParams.set('scope', options.history ? 'history' : 'selected');
+    if (options.includeExports)
+        manifestUrl.searchParams.set('exports', 'true');
+    let token = await options.key();
+    let refreshed = false;
+    const authed = async (url) => {
+        const run = (bearer) => fetchFn(url, { headers: { authorization: `Bearer ${bearer}` } });
+        let response = await run(token);
+        if (response.status === 401 && !refreshed) {
+            refreshed = true;
+            token = await options.refresh();
+            response = await run(token);
+        }
+        return response;
+    };
+    const listed = await authed(manifestUrl.href);
+    if (!listed.ok) {
+        throw new Error(`OpenStory could not list assets (${listed.status}) ${await errorText(listed)}`);
+    }
+    const manifest = await listed.json();
+    const assets = readAssets(manifest);
+    for (const asset of assets) {
+        if (!safeRelativePath(asset.relativePath)) {
+            throw new Error(`Refusing to write ${asset.relativePath}`);
+        }
+        if (asset.url != null && !asset.url.startsWith('/')) {
+            throw new Error(`Refusing ${asset.url}`);
+        }
+    }
+    const previous = await previousVersions(options.dest);
+    const present = new Set();
+    for (const asset of assets) {
+        if (previous.get(asset.relativePath) === asset.versionId &&
+            (await fileExists(options.dest, asset.relativePath))) {
+            present.add(asset.relativePath);
+        }
+    }
+    const todo = assets.filter((asset) => {
+        if (asset.url == null && asset.text == null)
+            return false;
+        return !present.has(asset.relativePath);
+    });
+    for (const asset of todo) {
+        const dest = join(options.dest, asset.relativePath);
+        const cache = asset.shared
+            ? sharedCacheFile(options.cacheDir, asset)
+            : null;
+        if (asset.text != null) {
+            await writeCached(dest, cache, async (file) => {
+                await mkdir(dirname(file), { recursive: true });
+                await writeFile(file, asset.text ?? '', 'utf8');
+            });
+        }
+        else if (asset.url != null) {
+            const fileUrl = new URL(asset.url, options.origin).href;
+            await writeCached(dest, cache, (file) => downloadTo(file, fileUrl, authed));
+        }
+    }
+    // Only paths an earlier manifest listed: anything else in the folder is the user's.
+    const listedNow = new Set(assets.map((asset) => asset.relativePath));
+    let removed = 0;
+    const root = await realpath(options.dest).catch(() => null);
+    for (const path of previous.keys()) {
+        if (root === null)
+            break;
+        if (listedNow.has(path) || !safeRelativePath(path))
+            continue;
+        if (!(await fileExists(options.dest, path)))
+            continue;
+        // A symlinked folder inside dest must not lead the delete outside it.
+        const target = await realpath(join(options.dest, path));
+        if (!target.startsWith(`${root}${sep}`))
+            continue;
+        await rm(target);
+        await pruneEmptyDirs(options.dest, dirname(path));
+        removed += 1;
+    }
+    await mkdir(options.dest, { recursive: true });
+    await writeFile(join(options.dest, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+    const skipped = assets.length - todo.length;
+    return { saved: todo.length, skipped, removed };
+}
+/** Removes `dir` and its parents while empty, stopping at `root`. */
+async function pruneEmptyDirs(root, dir) {
+    for (let rel = dir; rel !== '.' && rel !== ''; rel = dirname(rel)) {
+        try {
+            await rmdir(join(root, rel));
+        }
+        catch {
+            return;
+        }
+    }
+}
+async function writeCached(dest, cache, write) {
+    await mkdir(dirname(dest), { recursive: true });
+    if (!cache) {
+        await write(dest);
+        return;
+    }
+    let cached = false;
+    try {
+        await stat(cache);
+        cached = true;
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    if (!cached)
+        await write(cache);
+    await linkOver(cache, dest);
+}
+async function downloadTo(file, url, authed) {
+    const response = await authed(url);
+    if (!response.ok || response.body == null) {
+        throw new Error(`OpenStory could not download ${url} (${response.status}) ${await errorText(response)}`);
+    }
+    await mkdir(dirname(file), { recursive: true });
+    const partial = `${file}.partial`;
+    const writable = createWriteStream(partial);
+    const reader = response.body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value && !writable.write(value))
+                await once(writable, 'drain');
+        }
+        writable.end();
+        await once(writable, 'finish');
+    }
+    catch (error) {
+        writable.destroy();
+        await rm(partial, { force: true });
+        throw error;
+    }
+    await rename(partial, file);
+}
+async function linkOver(from, to) {
+    await mkdir(dirname(to), { recursive: true });
+    await rm(to, { force: true });
+    try {
+        await link(from, to);
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error !== null && 'code' in error
+            ? error.code
+            : '';
+        if (code === 'EXDEV' || code === 'EPERM') {
+            await copyFile(from, to);
+            return;
+        }
+        throw error;
+    }
+}
+function recordOf(value) {
+    return typeof value === 'object' && value !== null
+        ? Object.fromEntries(Object.entries(value))
+        : {};
+}
+function readAssets(manifest) {
+    if (!manifest || typeof manifest !== 'object' || !('assets' in manifest)) {
+        throw new Error('OpenStory answered without an asset list');
+    }
+    const assets = manifest.assets;
+    if (!Array.isArray(assets)) {
+        throw new Error('OpenStory answered without an asset list');
+    }
+    return assets.map((asset, index) => {
+        if (!asset || typeof asset !== 'object') {
+            throw new Error(`Asset ${index} is not an object`);
+        }
+        const row = recordOf(asset);
+        const relativePath = row.relativePath;
+        const versionId = row.versionId;
+        if (typeof relativePath !== 'string' || typeof versionId !== 'string') {
+            throw new Error(`Asset ${index} has no path`);
+        }
+        return {
+            relativePath,
+            versionId,
+            url: typeof row.url === 'string' ? row.url : null,
+            text: typeof row.text === 'string' ? row.text : null,
+            shared: row.shared === true,
+        };
+    });
+}
+async function previousVersions(dest) {
+    let text;
+    try {
+        text = await readFile(join(dest, 'manifest.json'), 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return new Map();
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return new Map();
+    }
+    const versions = new Map();
+    if (!parsed || typeof parsed !== 'object' || !('assets' in parsed)) {
+        return versions;
+    }
+    const assets = parsed.assets;
+    if (!Array.isArray(assets))
+        return versions;
+    for (const asset of assets) {
+        if (!asset || typeof asset !== 'object')
+            continue;
+        const path = 'relativePath' in asset ? asset.relativePath : null;
+        const versionId = 'versionId' in asset ? asset.versionId : null;
+        if (typeof path === 'string' && typeof versionId === 'string') {
+            versions.set(path, versionId);
+        }
+    }
+    return versions;
+}
+/** One cache file per stored url. A sheet and its portrait must not collide. */
+function sharedCacheFile(cacheDir, asset) {
+    const ext = extname(asset.relativePath);
+    const identity = asset.url
+        ? (asset.url.split('?')[0] ?? asset.url)
+        : `${asset.versionId}${ext}`;
+    const name = createHash('sha256').update(identity).digest('hex');
+    return join(cacheDir, `${name}${ext}`);
+}
+function safeRelativePath(path) {
+    if (path.startsWith('/') || path.includes('\\') || path.includes('\0')) {
+        return false;
+    }
+    return path
+        .split('/')
+        .every((part) => part !== '' && part !== '.' && part !== '..');
+}
+async function fileExists(dest, relativePath) {
+    try {
+        const info = await stat(join(dest, relativePath));
+        return info.isFile();
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
+function isMissing(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+async function errorText(response) {
+    try {
+        return (await response.text()).slice(0, 200);
+    }
+    catch {
+        return '';
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+/** `openstory`: the OpenStory account commands. stitch plays cuts; this talks to openstory.so. */
+import type { Writer } from './context.js';
+export declare const usage: string;
+export declare function main(argv: string[], io?: {
+    cwd?: string;
+    stdout?: Writer;
+    stderr?: Writer;
+    home?: string;
+    open?: (url: string) => void;
+    fetch?: typeof fetch;
+    now?: () => number;
+}): Promise<void>;
+export declare function openUrl(url: string, stderr: Writer): void;

package/dist/cli.js

@@ -0,0 +1,109 @@
+/** `openstory`: the OpenStory account commands. stitch plays cuts; this talks to openstory.so. */
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { CLI_VERSION, versionedFetch } from './api.js';
+import { login, moveOldCredentials } from './login.js';
+import { pull } from './pull.js';
+import { share } from './share.js';
+import { sync } from './sync.js';
+import { updateNotice } from './update-notice.js';
+/** One line per subcommand; each lives in its own file. */
+const COMMANDS = { login, pull, share, sync };
+export const usage = `Usage: ${Object.values(COMMANDS)
+    .map((command) => command.usage)
+    .join('\n       ')}
+
+openstory login signs in with a device code: it prints a short code and
+opens the approval page. The key is kept in ~/.openstory/credentials.json,
+one per server. pull and share sign in the same way on first use.
+
+openstory pull downloads a sequence into ./<sequenceId> (or --dir). A later
+run skips a file that is already there at the same version. --history adds
+every completed version. --exports adds rendered MP4s.
+
+openstory share uploads a cut (the same arguments as stitch) to OpenStory
+and prints a link anyone can open. Every still is checked for a real person;
+one who is needs --portrait-rights with the basis for using their likeness
+(a release reference, "self", a contract id).
+
+openstory sync mirrors every sequence of the key's organization into
+~/openstory/<organization>/<sequence>/ (or --dir), then keeps it current
+until stopped. Your sign-up organization is personal/. The folder is output
+only: OpenStory never reads it back, and a renamed sequence renames its
+folder. --once stops after the first pass.
+
+--origin picks the OpenStory server (default https://openstory.so).
+Run it with npx @openstory/cli@latest <command>.
+`;
+export async function main(argv, io = {}) {
+    const stdout = io.stdout ?? process.stdout;
+    const stderr = io.stderr ?? process.stderr;
+    const home = io.home ?? homedir();
+    const rawFetch = io.fetch ?? fetch;
+    // Only a person at a terminal sees the hint; tests inject stderr.
+    const notice = { hint: null };
+    if (io.stderr === undefined && process.stderr.isTTY && !process.env.CI) {
+        void updateNotice({
+            home,
+            current: CLI_VERSION,
+            now: (io.now ?? Date.now)(),
+            fetch: rawFetch,
+        }).then((text) => {
+            notice.hint = text;
+        });
+    }
+    try {
+        const [name, ...args] = argv;
+        if (name === '--version' || name === '-v') {
+            stdout.write(`${CLI_VERSION}\n`);
+            return;
+        }
+        if (name === undefined || name === '--help' || name === '-h') {
+            stdout.write(usage);
+            return;
+        }
+        const command = COMMANDS[name];
+        if (command === undefined) {
+            throw new Error(`Unknown command: ${name}. Run openstory --help`);
+        }
+        if (args.includes('--help') || args.includes('-h')) {
+            stdout.write(`Usage: ${command.usage}\n`);
+            return;
+        }
+        await moveOldCredentials(home);
+        await command.run(args, {
+            cwd: io.cwd ?? process.cwd(),
+            home,
+            stdout,
+            stderr,
+            open: io.open ?? ((url) => openUrl(url, stderr)),
+            fetch: versionedFetch(rawFetch),
+        });
+    }
+    catch (error) {
+        stderr.write(`${error instanceof Error ? error.message : 'openstory failed'}\n`);
+        process.exitCode = 1;
+    }
+    finally {
+        if (notice.hint !== null)
+            stderr.write(notice.hint);
+    }
+}
+export function openUrl(url, stderr) {
+    // Windows goes through rundll32, not `cmd /c start`: cmd parses & and ^
+    // in a URL, and the sign-in URL comes from the server.
+    const command = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32'
+            ? 'rundll32'
+            : 'xdg-open';
+    const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    const failed = (reason) => stderr.write(`Could not open a browser (${reason}). Open ${url}\n`);
+    child.on('error', (error) => failed(error.message));
+    child.on('exit', (code) => {
+        if (code !== 0 && code !== null)
+            failed(`${command} exited ${code}`);
+    });
+    child.unref();
+}

package/dist/context.d.ts

@@ -0,0 +1,23 @@
+/** What every subcommand gets, and the flags they share. */
+export type Writer = {
+    write: (text: string) => void;
+};
+export type CliContext = {
+    cwd: string;
+    home: string;
+    stdout: Writer;
+    stderr: Writer;
+    open: (url: string) => void;
+    /** Sends the version header and turns a 426 into an error; OpenStory only. */
+    fetch: typeof fetch;
+};
+/** A subcommand: one file under src/, one line in COMMANDS (cli.ts). */
+export type Command = {
+    usage: string;
+    run: (args: string[], context: CliContext) => Promise<void>;
+};
+/** Takes `--origin url` out of the args; the rest are the command's own. */
+export declare function parseOrigin(args: string[]): {
+    origin: string;
+    rest: string[];
+};

package/dist/context.js

@@ -0,0 +1,22 @@
+/** What every subcommand gets, and the flags they share. */
+import { isHttpUrl } from '@openstory/stitch/bundle';
+const DEFAULT_ORIGIN = 'https://openstory.so';
+/** Takes `--origin url` out of the args; the rest are the command's own. */
+export function parseOrigin(args) {
+    let origin = DEFAULT_ORIGIN;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? '';
+        if (arg === '--origin') {
+            const value = args[i + 1];
+            if (value === undefined || !isHttpUrl(value)) {
+                throw new Error('--origin needs an http(s) URL');
+            }
+            origin = new URL(value).origin;
+            i += 1;
+        }
+        else
+            rest.push(arg);
+    }
+    return { origin, rest };
+}

package/dist/login.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Signing in to OpenStory with the public API's device code, and the keys it
+ * leaves in ~/.openstory/credentials.json, one per origin.
+ */
+import type { CliContext, Command } from './context.js';
+export type SignInOptions = Pick<CliContext, 'home' | 'stderr' | 'open' | 'fetch'> & {
+    origin: string;
+};
+export declare const login: Command;
+/** Renames stitch's key file once; never over an existing credentials file. */
+export declare function moveOldCredentials(home: string): Promise<void>;
+/** The stored key, or a fresh device-code sign-in. */
+export declare function openStoryApiKey(options: SignInOptions): Promise<string>;
+export declare function storedKey(home: string, origin: string): Promise<string | null>;
+export declare function isMissingFile(error: unknown): boolean;
+/** Device-code sign-in (RFC 8628 shape); stores and returns the API key. */
+export declare function signIn(options: SignInOptions): Promise<string>;