@stigg/terminal 0.0.1-alpha

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Stigg
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @stigg/terminal
+
+> Interactive setup TUI for wiring [Stigg](https://stigg.io) into your AI coding assistants.
+
+`@stigg/terminal` is a terminal app that connects your editor's AI agent (Claude Code, Claude
+Desktop, Cursor, VS Code, Codex, …) to Stigg — authenticating you, writing the Stigg MCP server
+into each client's config, and installing the Stigg skills, all from one place.
+
+> ⚠️ **Alpha** (`0.0.1-alpha`) — under active development; expect breaking changes.
+
+## Requirements
+
+- Node.js **>= 22**
+
+## Usage
+
+Run it directly with `npx` (no install needed):
+
+```bash
+npx @stigg/terminal
+```
+
+With no arguments in an interactive terminal, it launches the full-screen setup TUI.
+
+Or install globally and use the `stiggt` command:
+
+```bash
+npm i -g @stigg/terminal
+stiggt
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| _(no args)_ | Launch the interactive setup TUI |
+| `init` | Set up Stigg in this project — auth, MCP, and skills. Add `--headless` for a non-interactive run, `--json` for machine-readable output |
+| `mcp add` | Write the Stigg MCP entry into one or more AI client configs (non-interactive) |
+| `skills add` | Install the Stigg skills for one or more AI clients (non-interactive) |
+| `env` | Switch the active Stigg environment |
+| `dash` | Open the Stigg dashboard in your browser |
+
+Run `stiggt <command> --help` for the full set of flags on any command.
+
+## License
+
+ISC

package/dist/api/client.d.ts

@@ -0,0 +1,6 @@
+import type { Account } from '../types.js';
+import type { ApiKey, CreateScopedKeyOptions, Environment } from './types.js';
+export declare function listAccounts(accessToken: string): Promise<Account[]>;
+export declare function listEnvironments(accessToken: string, accountId: string): Promise<Environment[]>;
+export declare function listApiKeys(accessToken: string, accountId: string, envId: string): Promise<ApiKey[]>;
+export declare function createScopedApiKey(accessToken: string, accountId: string, envId: string, opts?: CreateScopedKeyOptions): Promise<string>;

package/dist/api/client.js

@@ -0,0 +1,48 @@
+import { getGqlClient, gqlRequest } from './graphql-client.js';
+import { API_KEYS_QUERY, CREATE_SCOPED_API_KEY_MUTATION, CURRENT_USER_QUERY, ENVIRONMENTS_QUERY, fullScopeGrid, } from './operations.js';
+function lastFour(s) {
+    return s.slice(-4);
+}
+export async function listAccounts(accessToken) {
+    const client = getGqlClient(accessToken);
+    const data = await gqlRequest(client, CURRENT_USER_QUERY);
+    return data.currentUser.memberships.map((m) => ({
+        id: m.account.id,
+        displayName: m.account.displayName,
+    }));
+}
+export async function listEnvironments(accessToken, accountId) {
+    const client = getGqlClient(accessToken, accountId);
+    const data = await gqlRequest(client, ENVIRONMENTS_QUERY);
+    return data.environments.edges.map(({ node }) => ({
+        id: node.id,
+        name: node.displayName,
+        slug: node.slug,
+    }));
+}
+export async function listApiKeys(accessToken, accountId, envId) {
+    const client = getGqlClient(accessToken, accountId);
+    const data = await gqlRequest(client, API_KEYS_QUERY, {
+        envId,
+    });
+    return data.apiKeys.edges.map(({ node }) => ({
+        id: node.id,
+        name: node.displayName,
+        lastFour: lastFour(node.token),
+        scopes: ['read', 'write'],
+        keyType: node.keyType,
+        createdAt: node.createdAt,
+        value: node.token,
+    }));
+}
+export async function createScopedApiKey(accessToken, accountId, envId, opts = {}) {
+    const client = getGqlClient(accessToken, accountId);
+    const data = await gqlRequest(client, CREATE_SCOPED_API_KEY_MUTATION, {
+        input: {
+            displayName: opts.name ?? 'stigg-terminal-mcp',
+            environmentId: envId,
+            scopes: fullScopeGrid(),
+        },
+    });
+    return data.createScopedApiKey.token;
+}

package/dist/api/format-key.d.ts

@@ -0,0 +1,7 @@
+import type { ApiKey } from '../types.js';
+/**
+ * Render a key's identity for UI display: first 8 chars of the secret +
+ * `…` + last 4. Falls back to `…lastFour` when the secret value isn't
+ * loaded (partial responses).
+ */
+export declare function formatApiKeyShort(key: Pick<ApiKey, 'value' | 'lastFour'>): string;

package/dist/api/format-key.js

@@ -0,0 +1,12 @@
+/**
+ * Render a key's identity for UI display: first 8 chars of the secret +
+ * `…` + last 4. Falls back to `…lastFour` when the secret value isn't
+ * loaded (partial responses).
+ */
+export function formatApiKeyShort(key) {
+    if (!key.value)
+        return `…${key.lastFour}`;
+    if (key.value.length <= 12)
+        return key.value;
+    return `${key.value.slice(0, 8)}…${key.lastFour}`;
+}

package/dist/api/graphql-client.d.ts

@@ -0,0 +1,5 @@
+import { GraphQLClient } from 'graphql-request';
+export declare function graphqlEndpoint(): string;
+export declare function getGqlClient(accessToken: string, accountId?: string): GraphQLClient;
+export declare function formatGqlError(err: unknown): string;
+export declare function gqlRequest<T>(client: GraphQLClient, query: string, variables?: Record<string, unknown>): Promise<T>;

package/dist/api/graphql-client.js

@@ -0,0 +1,44 @@
+import { GraphQLClient } from 'graphql-request';
+import { optionalEnv } from '../auth/config.js';
+const DEFAULT_URL = 'https://api.stigg.io/graphql';
+export function graphqlEndpoint() {
+    return optionalEnv('STIGG_API_URL') ?? DEFAULT_URL;
+}
+export function getGqlClient(accessToken, accountId) {
+    const headers = {
+        Authorization: `Bearer ${accessToken}`,
+    };
+    if (accountId)
+        headers['X-Account-Id'] = accountId;
+    return new GraphQLClient(graphqlEndpoint(), { headers });
+}
+export function formatGqlError(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    const gql = err;
+    const gqlErrors = gql.response?.errors;
+    if (gqlErrors && gqlErrors.length > 0) {
+        const msgs = gqlErrors.map((e) => e.message ?? '(no message)').join('; ');
+        const status = gql.response?.status;
+        return status ? `GraphQL ${status}: ${msgs}` : `GraphQL error: ${msgs}`;
+    }
+    const cause = err.cause;
+    if (cause instanceof Error || (cause && typeof cause === 'object')) {
+        const c = cause;
+        const detail = c.code ? `${c.code}${c.message ? ` — ${c.message}` : ''}` : c.message;
+        if (detail)
+            return `${err.message} → ${detail} (${graphqlEndpoint()})`;
+    }
+    if (/fetch failed/i.test(err.message)) {
+        return `${err.message} (${graphqlEndpoint()})`;
+    }
+    return err.message;
+}
+export async function gqlRequest(client, query, variables) {
+    try {
+        return await client.request(query, variables);
+    }
+    catch (err) {
+        throw new Error(formatGqlError(err));
+    }
+}

package/dist/api/operations.d.ts

@@ -0,0 +1,65 @@
+export declare const CURRENT_USER_QUERY = "\n  query StiggTerminalCurrentUser {\n    currentUser {\n      id\n      email\n      name\n      memberships {\n        id\n        account {\n          id\n          displayName\n        }\n      }\n    }\n  }\n";
+export declare const ENVIRONMENTS_QUERY = "\n  query StiggTerminalEnvironments {\n    environments(\n      filter: { permanentDeletionDate: { is: null } }\n      paging: { first: 50 }\n    ) {\n      edges {\n        node {\n          id\n          slug\n          displayName\n          type\n          color\n        }\n      }\n    }\n  }\n";
+export declare const API_KEYS_QUERY = "\n  query StiggTerminalApiKeys($envId: UUID!) {\n    apiKeys(input: { environmentId: $envId, keyTypes: [SERVER, SCOPED], paging: { first: 50 } }) {\n      edges {\n        node {\n          id\n          displayName\n          token\n          keyType\n          createdAt\n        }\n      }\n    }\n  }\n";
+export declare const CREATE_SCOPED_API_KEY_MUTATION = "\n  mutation StiggTerminalCreateScopedApiKey($input: CreateScopedApiKeyInput!) {\n    createScopedApiKey(input: $input) {\n      id\n      displayName\n      token\n      createdAt\n    }\n  }\n";
+export interface CurrentUserResult {
+    currentUser: {
+        id: string;
+        email: string | null;
+        name: string | null;
+        memberships: Array<{
+            id: string;
+            account: {
+                id: string;
+                displayName: string;
+            };
+        }>;
+    };
+}
+export interface EnvironmentsResult {
+    environments: {
+        edges: Array<{
+            node: {
+                id: string;
+                slug: string;
+                displayName: string;
+                type: string;
+                color: string | null;
+            };
+        }>;
+    };
+}
+export interface ApiKeysResult {
+    apiKeys: {
+        edges: Array<{
+            node: {
+                id: string;
+                displayName: string;
+                token: string;
+                keyType: string;
+                createdAt: string;
+            };
+        }>;
+    };
+}
+export interface CreateScopedApiKeyResult {
+    createScopedApiKey: {
+        id: string;
+        displayName: string;
+        token: string;
+        createdAt: string;
+    };
+}
+export type ApiKeyScopeAction = 'READ' | 'WRITE';
+export type ApiKeyScopeResource = 'API_KEY' | 'COUPON' | 'CUSTOMER' | 'ENVIRONMENT' | 'EVENT_QUEUE' | 'SUBSCRIPTION';
+export interface ApiKeyScopeInput {
+    action: ApiKeyScopeAction;
+    resource: ApiKeyScopeResource;
+}
+export interface CreateScopedApiKeyInput {
+    description?: string;
+    displayName: string;
+    environmentId: string;
+    scopes: ApiKeyScopeInput[];
+}
+export declare function fullScopeGrid(): ApiKeyScopeInput[];

package/dist/api/operations.js

@@ -0,0 +1,77 @@
+export const CURRENT_USER_QUERY = /* GraphQL */ `
+  query StiggTerminalCurrentUser {
+    currentUser {
+      id
+      email
+      name
+      memberships {
+        id
+        account {
+          id
+          displayName
+        }
+      }
+    }
+  }
+`;
+export const ENVIRONMENTS_QUERY = /* GraphQL */ `
+  query StiggTerminalEnvironments {
+    environments(
+      filter: { permanentDeletionDate: { is: null } }
+      paging: { first: 50 }
+    ) {
+      edges {
+        node {
+          id
+          slug
+          displayName
+          type
+          color
+        }
+      }
+    }
+  }
+`;
+export const API_KEYS_QUERY = /* GraphQL */ `
+  query StiggTerminalApiKeys($envId: UUID!) {
+    apiKeys(input: { environmentId: $envId, keyTypes: [SERVER, SCOPED], paging: { first: 50 } }) {
+      edges {
+        node {
+          id
+          displayName
+          token
+          keyType
+          createdAt
+        }
+      }
+    }
+  }
+`;
+export const CREATE_SCOPED_API_KEY_MUTATION = /* GraphQL */ `
+  mutation StiggTerminalCreateScopedApiKey($input: CreateScopedApiKeyInput!) {
+    createScopedApiKey(input: $input) {
+      id
+      displayName
+      token
+      createdAt
+    }
+  }
+`;
+const ALL_RESOURCES = [
+    'API_KEY',
+    'COUPON',
+    'CUSTOMER',
+    'ENVIRONMENT',
+    'EVENT_QUEUE',
+    'SUBSCRIPTION',
+];
+export function fullScopeGrid() {
+    const scopes = [];
+    for (const resource of ALL_RESOURCES) {
+        scopes.push({ action: 'READ', resource });
+        if (resource !== 'EVENT_QUEUE') {
+            scopes.push({ action: 'WRITE', resource });
+        }
+    }
+    return scopes;
+}

package/dist/api/types.d.ts

@@ -0,0 +1,18 @@
+export interface Environment {
+    id: string;
+    name: string;
+    slug?: string;
+}
+export interface CreateScopedKeyOptions {
+    name?: string;
+    scopes?: 'godmode' | string;
+}
+export interface ApiKey {
+    id: string;
+    name: string;
+    lastFour: string;
+    scopes: string[];
+    keyType: string;
+    createdAt: string;
+    value?: string;
+}

package/dist/api/types.js

@@ -0,0 +1 @@
+export {};

package/dist/auth/callback-server.d.ts

@@ -0,0 +1,14 @@
+export interface CallbackServer {
+    port: number;
+    awaitCallback(): Promise<URL>;
+    close(): void;
+}
+export interface StartCallbackServerOptions {
+    /**
+     * Loopback port to bind to. When omitted (or 0), the OS picks a free port.
+     * Production runs always pass a fixed port so a single
+     * `http://127.0.0.1:<port>/callback` can be whitelisted in the Auth0 app.
+     */
+    port?: number;
+}
+export declare function startCallbackServer(options?: StartCallbackServerOptions): Promise<CallbackServer>;

package/dist/auth/callback-server.js

@@ -0,0 +1,145 @@
+import { createServer } from 'node:http';
+export async function startCallbackServer(options = {}) {
+    let resolveCallback;
+    let rejectCallback;
+    const callbackPromise = new Promise((resolve, reject) => {
+        resolveCallback = resolve;
+        rejectCallback = reject;
+    });
+    let server;
+    server = createServer((req, res) => {
+        if (!req.url) {
+            res.writeHead(400).end();
+            return;
+        }
+        const port = server.address()?.port ?? 0;
+        const url = new URL(req.url, `http://127.0.0.1:${port}`);
+        if (url.pathname !== '/callback') {
+            res.writeHead(404, { 'Content-Type': 'text/plain' }).end('Not found');
+            return;
+        }
+        const err = url.searchParams.get('error');
+        if (err) {
+            const desc = url.searchParams.get('error_description') ?? '';
+            res
+                .writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' })
+                .end(renderPage(false, `${err}${desc ? `: ${desc}` : ''}`));
+            rejectCallback(new Error(`Auth0 callback returned error: ${err} ${desc}`));
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' }).end(renderPage(true));
+        resolveCallback(url);
+    });
+    const requestedPort = options.port ?? 0;
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(requestedPort, '127.0.0.1', () => {
+            server.off('error', reject);
+            resolve();
+        });
+    }).catch((err) => {
+        if (err.code === 'EADDRINUSE') {
+            throw new Error(`Port ${requestedPort} is already in use. Free it up, or pass a different ` +
+                `port via --callback-port <port> (must be whitelisted in the Auth0 app).`);
+        }
+        throw err;
+    });
+    const addr = server.address();
+    return {
+        port: addr.port,
+        awaitCallback: () => callbackPromise,
+        close: () => {
+            server.close();
+        },
+    };
+}
+function renderPage(success, message) {
+    const accent = success ? '#9eff00' : '#ff4d4d';
+    const accentDim = success ? 'rgba(158, 255, 0, 0.45)' : 'rgba(255, 77, 77, 0.45)';
+    const line1 = success ? 'Stigg login complete!' : 'Stigg login failed.';
+    const line2 = success
+        ? 'Return to your terminal &mdash; setup continues there'
+        : `Reason: ${escapeHtml(message ?? 'unknown error')}`;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Stigg · terminal</title>
+<style>
+  :root { color-scheme: dark; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    background: #050505;
+    color: ${accent};
+    font-family: "Menlo", "SF Mono", "Monaco", "Consolas", "Liberation Mono", "Courier New", monospace;
+    font-size: 18px;
+    line-height: 1.6;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    text-shadow: 0 0 8px ${accentDim};
+    overflow: hidden;
+  }
+  main {
+    text-align: left;
+    padding: 0 24px;
+    max-width: 720px;
+  }
+  .line { margin: 0; white-space: pre; }
+  .cursor {
+    display: inline-block;
+    width: 0.55em;
+    height: 1em;
+    background: ${accent};
+    vertical-align: -0.12em;
+    margin-left: 4px;
+    box-shadow: 0 0 8px ${accentDim};
+    animation: blink 1s steps(2, start) infinite;
+  }
+  @keyframes blink {
+    to { background: transparent; box-shadow: none; }
+  }
+  /* CRT scanline overlay */
+  body::after {
+    content: "";
+    position: fixed;
+    inset: 0;
+    pointer-events: none;
+    background: repeating-linear-gradient(
+      to bottom,
+      rgba(0, 0, 0, 0) 0px,
+      rgba(0, 0, 0, 0) 2px,
+      rgba(0, 0, 0, 0.18) 3px,
+      rgba(0, 0, 0, 0.18) 4px
+    );
+  }
+  /* Subtle CRT vignette */
+  body::before {
+    content: "";
+    position: fixed;
+    inset: 0;
+    pointer-events: none;
+    background: radial-gradient(
+      ellipse at center,
+      rgba(0, 0, 0, 0) 60%,
+      rgba(0, 0, 0, 0.55) 100%
+    );
+  }
+</style>
+</head>
+<body>
+  <main>
+    <p class="line">${line1}</p>
+    <p class="line">${line2}<span class="cursor"></span></p>
+  </main>
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}

package/dist/auth/config.d.ts

@@ -0,0 +1,2 @@
+export declare function loadEnv(): void;
+export declare function optionalEnv(name: string): string | undefined;

package/dist/auth/config.js

@@ -0,0 +1,24 @@
+let envLoaded = false;
+export function loadEnv() {
+    if (envLoaded)
+        return;
+    envLoaded = true;
+    // .env.local takes precedence over .env (machine-specific overrides win).
+    // process.loadEnvFile() only sets vars that aren't already in process.env,
+    // so shell vars beat both files and the first file loaded wins between them.
+    for (const file of ['.env.local', '.env']) {
+        try {
+            process.loadEnvFile(file);
+        }
+        catch {
+            // file not present in cwd — fine, try the next
+        }
+    }
+}
+export function optionalEnv(name) {
+    loadEnv();
+    const val = process.env[name];
+    if (!val || val.startsWith('<'))
+        return undefined;
+    return val;
+}

package/dist/auth/oauth.d.ts

@@ -0,0 +1,17 @@
+export interface AuthSession {
+    access_token: string;
+    refresh_token?: string;
+    id_token: string;
+    expires_at: number;
+    email: string;
+    sub: string;
+    scope?: string;
+}
+export interface AuthenticateOptions {
+    onAuthUrlReady?: (url: string, port: number) => void;
+    timeoutMs?: number;
+    /** Fixed loopback port for the OAuth callback. Takes precedence over
+     *  `STIGG_CALLBACK_PORT`, which in turn overrides the built-in default. */
+    port?: number;
+}
+export declare function authenticate(opts?: AuthenticateOptions): Promise<AuthSession>;

package/dist/auth/oauth.js

@@ -0,0 +1,94 @@
+import * as openid from 'openid-client';
+import open from 'open';
+import { optionalEnv } from './config.js';
+import { startCallbackServer } from './callback-server.js';
+const DEFAULT_AUTH0_DOMAIN = 'auth.stigg.io';
+const DEFAULT_CLI_CLIENT_ID = 'NCcMvD7YNFUGfCUSrkq6HxiqHe0aqTc5';
+const DEFAULT_AUDIENCE = 'https://api.stigg.io/';
+const DEFAULT_SCOPE = 'openid email profile offline_access';
+// Static loopback port for the OAuth callback so a single
+// http://127.0.0.1:<port>/callback can be whitelisted in the Auth0 app.
+const DEFAULT_CALLBACK_PORT = 57166;
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+export async function authenticate(opts = {}) {
+    const domain = optionalEnv('STIGG_AUTH0_DOMAIN') ?? DEFAULT_AUTH0_DOMAIN;
+    const clientId = optionalEnv('STIGG_CLI_CLIENT_ID') ?? DEFAULT_CLI_CLIENT_ID;
+    const audience = optionalEnv('STIGG_AUDIENCE') ?? DEFAULT_AUDIENCE;
+    const scope = optionalEnv('STIGG_AUTH0_SCOPE') ?? DEFAULT_SCOPE;
+    const fixedPort = resolveCallbackPort(opts.port);
+    const config = await openid.discovery(new URL(`https://${domain}`), clientId);
+    const codeVerifier = openid.randomPKCECodeVerifier();
+    const codeChallenge = await openid.calculatePKCECodeChallenge(codeVerifier);
+    const state = openid.randomState();
+    const server = await startCallbackServer({ port: fixedPort });
+    const redirectUri = `http://127.0.0.1:${server.port}/callback`;
+    const authUrl = openid.buildAuthorizationUrl(config, {
+        redirect_uri: redirectUri,
+        scope,
+        audience,
+        code_challenge: codeChallenge,
+        code_challenge_method: 'S256',
+        state,
+    });
+    opts.onAuthUrlReady?.(authUrl.href, server.port);
+    try {
+        await open(authUrl.href);
+    }
+    catch {
+        // browser couldn't open — caller prints URL via onAuthUrlReady
+    }
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let timer;
+    try {
+        const callbackUrl = await Promise.race([
+            server.awaitCallback(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Login timed out after ${timeoutMs / 1000}s`)), timeoutMs);
+            }),
+        ]);
+        const tokens = await openid.authorizationCodeGrant(config, callbackUrl, {
+            pkceCodeVerifier: codeVerifier,
+            expectedState: state,
+        });
+        if (!tokens.id_token) {
+            throw new Error('Auth0 did not return an id_token');
+        }
+        const claims = decodeJwtPayload(tokens.id_token);
+        return {
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token,
+            id_token: tokens.id_token,
+            expires_at: Date.now() + (tokens.expires_in ?? 3600) * 1000,
+            email: typeof claims.email === 'string' ? claims.email : 'unknown',
+            sub: typeof claims.sub === 'string' ? claims.sub : 'unknown',
+            scope: tokens.scope,
+        };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        server.close();
+    }
+}
+function decodeJwtPayload(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3)
+        throw new Error('Malformed JWT');
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+}
+function resolveCallbackPort(cliPort) {
+    if (cliPort !== undefined) {
+        if (!Number.isInteger(cliPort) || cliPort < 1 || cliPort > 65535) {
+            throw new Error(`--callback-port must be an integer between 1 and 65535 (got "${cliPort}")`);
+        }
+        return cliPort;
+    }
+    const envPortStr = optionalEnv('STIGG_CALLBACK_PORT');
+    if (envPortStr === undefined)
+        return DEFAULT_CALLBACK_PORT;
+    const envPort = Number(envPortStr);
+    if (!Number.isInteger(envPort) || envPort < 1 || envPort > 65535) {
+        throw new Error(`STIGG_CALLBACK_PORT must be an integer between 1 and 65535 (got "${envPortStr}")`);
+    }
+    return envPort;
+}

package/dist/auth/storage.d.ts

@@ -0,0 +1,6 @@
+import type { AuthSession } from './oauth.js';
+export declare function configDir(): string;
+export declare function credentialsPath(): string;
+export declare function saveSession(session: AuthSession): Promise<string>;
+export declare function loadSession(): Promise<AuthSession | null>;
+export declare function clearSession(): Promise<void>;