@mx-space/cli 0.15.0 → 0.15.1

package/dist/src/services/Api.js

@@ -0,0 +1,348 @@
+import { HttpClient, HttpClientRequest } from '@effect/platform';
+import { Context, Effect, Layer, Ref } from 'effect';
+import { detectWireVersion, normalizeErrorBody, normalizeSuccessBody, } from '../domain/envelope-compat';
+import { AuthDenied, AuthExpired, Generic, NetworkDns, NetworkRefused, NetworkTimeout, ResourceNotFound, ServerError, ValidationFailed, WriteRequiresExplicit, } from '../domain/errors';
+import { decideWriteGate, } from '../domain/gate';
+import { USER_AGENT } from '../domain/version';
+import { Auth } from './Auth';
+import { Config } from './Config';
+export class Api extends Context.Tag('Api')() {
+    /**
+     * Default Layer: no overrides, banner + verbose enabled per env / config.
+     * Wave 2 entry-point (`bin/mxs.ts`) should use `Api.layer({...})` to wire
+     * flag-derived overrides through.
+     */
+    static Default = Api.layer({});
+    /** Build an Api Layer with command-specified overrides + UX flags. */
+    static layer(opts) {
+        return Layer.effect(Api, Effect.gen(function* () {
+            const http = yield* HttpClient.HttpClient;
+            const config = yield* Config;
+            const auth = yield* Auth;
+            return yield* makeApiService(http, config, auth, opts);
+        }));
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal: construct an `ApiService` given resolved deps.
+// ---------------------------------------------------------------------------
+function makeApiService(http, config, auth, opts) {
+    return Effect.gen(function* () {
+        const bannerEmitted = yield* Ref.make(false);
+        // COMPAT:envelope — diagnostic-only cache of the detected wire version.
+        // Used to enrich the `--verbose` log line. Drop with envelope-compat.ts.
+        const detectedWire = yield* Ref.make(null);
+        /**
+         * Resolved config is cached per `ApiService` instance. This matches
+         * today's `ApiClient` which is constructed once per command run.
+         */
+        const resolvedEffect = config.resolve(opts.overrides).pipe(Effect.mapError((err) => err._tag === 'Generic'
+            ? err
+            : new Generic({
+                message: 'failed to resolve config',
+                cause: err,
+            })));
+        const maybeEmitBanner = (resolved) => Effect.gen(function* () {
+            if (!resolved.isProduction || opts.quiet)
+                return;
+            const already = yield* Ref.get(bannerEmitted);
+            if (already)
+                return;
+            yield* Ref.set(bannerEmitted, true);
+            yield* Effect.sync(() => {
+                process.stderr.write(`mxs: profile=${resolved.profileName} (production) → ${resolved.apiUrl}\n`);
+            });
+        });
+        const request = (path, options = {}) => Effect.gen(function* () {
+            const resolved = yield* resolvedEffect;
+            yield* maybeEmitBanner(resolved);
+            const method = (options.method ?? 'GET');
+            // ---- 1. write-gate (pure decision; runs BEFORE network) ---------
+            const gateInput = {
+                apiUrl: resolved.apiUrl,
+                profileName: resolved.profileName,
+                isProduction: resolved.isProduction,
+                profileExplicit: resolved.profileExplicit,
+                urlOverridden: resolved.urlOverridden,
+            };
+            const decision = decideWriteGate(gateInput, method);
+            if (!decision.allow) {
+                return yield* Effect.fail(new WriteRequiresExplicit({
+                    message: decision.message,
+                    hint: decision.hint,
+                    profile: resolved.profileName ?? undefined,
+                    apiUrl: resolved.apiUrl,
+                    details: {
+                        profile: resolved.profileName,
+                        api_url: resolved.apiUrl,
+                    },
+                }));
+            }
+            // ---- 1b. --dry-run short-circuit (writes only; reads pass through)
+            if (opts.dryRun && method !== 'GET') {
+                if (opts.verbose && !opts.quiet) {
+                    process.stderr.write(`mxs: dry-run — would send ${method} ${buildUrl(resolved.apiBase, path)}\n`);
+                }
+                // Return a synthetic envelope so command handlers stay uniform.
+                // No schema decoding — handlers that emit via Renderer treat this
+                // as a passthrough payload.
+                return {
+                    ok: true,
+                    status: 200,
+                    data: {
+                        dryRun: true,
+                        method,
+                        path,
+                        query: options.query ?? null,
+                        body: options.body ?? null,
+                    },
+                };
+            }
+            // ---- 2. auto-refresh near-expiry tokens -------------------------
+            let token = resolved.token;
+            if (token && resolved.profileName) {
+                const fresh = yield* auth
+                    .ensureFresh(resolved)
+                    .pipe(Effect.catchAll(() => Effect.succeed(null)));
+                if (fresh)
+                    token = fresh.access_token;
+            }
+            // ---- 3. send (with single 401-retry) ----------------------------
+            // Inject `lang` into the query for read-only requests when the bin
+            // has set a global `--lang` flag and the caller didn't already
+            // specify one.
+            const effectiveQuery = opts.lang && method === 'GET'
+                ? { lang: opts.lang, ...options.query }
+                : options.query;
+            const url = buildUrl(resolved.apiBase, path, effectiveQuery);
+            const baseHeaders = {
+                accept: 'application/json',
+                'user-agent': USER_AGENT,
+                ...options.headers,
+            };
+            if (token)
+                baseHeaders.authorization = `Bearer ${token}`;
+            if (resolved.apiKey)
+                baseHeaders['x-api-key'] = resolved.apiKey;
+            if (options.body !== undefined && !(options.body instanceof FormData)) {
+                baseHeaders['content-type'] ??= 'application/json';
+            }
+            const send = (headers) => Effect.gen(function* () {
+                const startedAt = Date.now();
+                let req = HttpClientRequest.make(method)(url, {
+                    headers,
+                });
+                if (options.body instanceof FormData) {
+                    req = HttpClientRequest.bodyFormData(req, options.body);
+                }
+                else if (options.body !== undefined) {
+                    req = yield* HttpClientRequest.bodyJson(req, options.body).pipe(Effect.mapError((err) => new Generic({
+                        message: 'failed to encode body',
+                        cause: err,
+                    })));
+                }
+                const res = yield* http.execute(req).pipe(Effect.mapError((err) => {
+                    if (err._tag === 'ResponseError') {
+                        // Non-2xx is not surfaced through here because we
+                        // don't apply filterStatusOk; if a custom layer does
+                        // raise ResponseError we fall through to Generic.
+                        return new Generic({
+                            message: 'unexpected response error',
+                            cause: err,
+                        });
+                    }
+                    return mapTransportError(err.cause ?? err, url);
+                }));
+                if (opts.verbose) {
+                    process.stderr.write(`${method} ${url} → ${res.status} (${Date.now() - startedAt}ms)\n`);
+                }
+                return res;
+            });
+            let headers = { ...baseHeaders };
+            let res = yield* send(headers);
+            if (res.status === 401 && token && resolved.profileName) {
+                const refreshed = yield* refreshOnce(auth, config, resolved, token).pipe(Effect.catchAll(() => Effect.succeed(null)));
+                if (refreshed) {
+                    token = refreshed.access_token;
+                    headers = { ...headers, authorization: `Bearer ${token}` };
+                    res = yield* send(headers);
+                }
+            }
+            // ---- 4. parse + status mapping ---------------------------------
+            const body = yield* parseBody(res);
+            // COMPAT:envelope — sniff wire version once per ApiService instance
+            // for verbose diagnostics. Normalizers below are shape-tolerant and
+            // do not consume this verdict. Drop with envelope-compat.ts.
+            if (opts.verbose) {
+                const cached = yield* Ref.get(detectedWire);
+                if (!cached) {
+                    const sniffed = detectWireVersion(body);
+                    if (sniffed) {
+                        yield* Ref.set(detectedWire, sniffed);
+                        process.stderr.write(`mxs: detected wire version: ${sniffed}\n`);
+                    }
+                }
+            }
+            if (res.status >= 200 && res.status < 300) {
+                // COMPAT:envelope — lift V2 root `pagination` to V3 `meta.pagination`.
+                const normalized = normalizeSuccessBody(body);
+                if (!options.schema)
+                    return normalized;
+                return yield* decodeWithSchema(options.schema, normalized);
+            }
+            return yield* Effect.fail(mapHttpStatusToError(res.status, body));
+        });
+        const raw = (path, options) => request(path, options);
+        return {
+            request,
+            raw,
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function buildUrl(base, path, query) {
+    const url = new URL(path.startsWith('/') ? path.slice(1) : path, base.endsWith('/') ? base : `${base}/`);
+    if (query) {
+        for (const [k, v] of Object.entries(query)) {
+            if (v === undefined || v === null)
+                continue;
+            url.searchParams.set(k, String(v));
+        }
+    }
+    return url.toString();
+}
+function parseBody(res) {
+    const ct = res.headers['content-type'] ?? '';
+    if (ct.includes('application/json')) {
+        return res.json.pipe(Effect.catchAll(() => Effect.succeed(undefined)));
+    }
+    return res.text.pipe(Effect.catchAll(() => Effect.succeed('')));
+}
+function decodeWithSchema(schema, body) {
+    // We use the platform `Schema.decodeUnknown` to validate at runtime.
+    // `effect/Schema` exposes the same API surface, so we import it lazily
+    // to keep the static `Api.ts` dep graph minimal.
+    return Effect.tryPromise({
+        try: async () => {
+            const { Schema: SchemaMod } = await import('effect');
+            return SchemaMod.decodeUnknownPromise(schema)(body);
+        },
+        catch: (err) => new ServerError({
+            status: 200,
+            message: 'response shape mismatch',
+            details: serializeParseError(err),
+        }),
+    });
+}
+function serializeParseError(err) {
+    if (err && typeof err === 'object') {
+        const message = err.message;
+        if (typeof message === 'string')
+            return message;
+    }
+    return err;
+}
+function mapHttpStatusToError(status, body) {
+    // COMPAT:envelope — flatten V2/V3 error body shapes to one tuple. Drop with
+    // envelope-compat.ts when V2 support ends; replace with direct
+    // `body.error?.message` reads.
+    const { code, message: serverMsg, details: serverDetails, } = normalizeErrorBody(body);
+    const details = serverDetails ?? body;
+    // Code-driven mapping wins over status-derived classification when the V3
+    // server emits a stable SCREAMING_SNAKE error code.
+    if (code === 'NOT_FOUND' || code?.endsWith('_NOT_FOUND')) {
+        return new ResourceNotFound({
+            message: serverMsg ?? 'resource not found',
+            details,
+        });
+    }
+    if (code === 'VALIDATION_FAILED') {
+        return new ValidationFailed({
+            message: serverMsg ?? 'validation failed',
+            details,
+        });
+    }
+    if (status === 401) {
+        return new AuthExpired({
+            message: serverMsg ?? 'authentication required',
+            hint: 'run `mxs auth login`',
+            details,
+        });
+    }
+    if (status === 403) {
+        return new AuthDenied({
+            message: serverMsg ?? 'permission denied',
+            details,
+        });
+    }
+    if (status === 404) {
+        return new ResourceNotFound({
+            message: serverMsg ?? 'resource not found',
+            details,
+        });
+    }
+    if (status === 400 || status === 422) {
+        return new ValidationFailed({
+            message: serverMsg ?? 'validation failed',
+            details,
+        });
+    }
+    if (status >= 500) {
+        return new ServerError({
+            status,
+            message: serverMsg ?? `server error (${status})`,
+            details,
+        });
+    }
+    return new Generic({
+        message: serverMsg ?? `request failed (${status})`,
+        details,
+    });
+}
+function mapTransportError(err, url) {
+    const cause = err;
+    const code = cause?.code ?? cause?.cause?.code;
+    if (cause?.name === 'AbortError' || code === 'ABORT_ERR') {
+        return new Generic({ message: 'request aborted', details: { url } });
+    }
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
+        let host = url;
+        try {
+            host = new URL(url).host;
+        }
+        catch { }
+        return new NetworkDns({
+            host,
+            message: 'dns lookup failed',
+            details: { url },
+        });
+    }
+    if (code === 'ECONNREFUSED') {
+        return new NetworkRefused({ url, message: 'connection refused' });
+    }
+    if (code === 'ETIMEDOUT' || code === 'UND_ERR_CONNECT_TIMEOUT') {
+        return new NetworkTimeout({ url, message: 'network request timed out' });
+    }
+    return new Generic({
+        message: cause?.message ?? `request failed: ${url}`,
+        details: { url, cause: code },
+    });
+}
+function refreshOnce(auth, config, resolved, currentToken) {
+    return Effect.gen(function* () {
+        if (!resolved.profileName)
+            return null;
+        const cred = yield* config.readProfileCredentials(resolved.profileName);
+        if (!cred)
+            return null;
+        if (cred.access_token !== currentToken)
+            return null;
+        const refreshed = yield* auth.refresh(resolved.authBase, resolved.clientId, cred);
+        if (!refreshed)
+            return null;
+        yield* config.writeProfileCredentials(resolved.profileName, refreshed);
+        return refreshed;
+    });
+}

package/dist/src/services/Auth.d.ts

@@ -0,0 +1,101 @@
+import { HttpClient } from '@effect/platform';
+import { Context, Effect, Layer } from 'effect';
+import { AuthDenied, AuthExpired, AuthMissing, AuthProbe, Generic, NetworkDns, NetworkRefused, NetworkTimeout } from '../domain/errors';
+import { Config, type CredentialsShape, type ResolvedConfig } from './Config';
+export interface AuthProbeResult {
+    readonly apiUrl: string;
+    readonly apiBase: string;
+    readonly authBase: string;
+    readonly apiVersion: number;
+}
+export interface WhoamiInfo {
+    readonly id?: string;
+    readonly email?: string;
+    readonly name?: string;
+    readonly expiresAt: number;
+}
+export interface AuthStatusInfo {
+    readonly authenticated: boolean;
+    readonly apiUrl: string;
+    readonly profile: string | null;
+    readonly expiresAt?: number;
+    readonly user?: WhoamiInfo;
+}
+export interface LoginOptions {
+    readonly profile?: string;
+    readonly apiUrl?: string;
+    readonly production?: boolean;
+    readonly signal?: AbortSignal;
+}
+export interface DeviceCodeResponse {
+    readonly device_code: string;
+    readonly user_code: string;
+    readonly verification_uri: string;
+    readonly verification_uri_complete?: string;
+    readonly expires_in: number;
+    readonly interval: number;
+}
+export interface DeviceTokenResponse {
+    readonly access_token: string;
+    readonly token_type: string;
+    readonly expires_in: number;
+    readonly refresh_token?: string;
+    readonly scope?: string;
+    readonly user?: {
+        readonly id?: string;
+        readonly email?: string;
+        readonly name?: string;
+    };
+}
+export interface PollDeviceTokenOptions {
+    readonly intervalSec: number;
+    readonly expiresInSec: number;
+    readonly signal?: AbortSignal;
+    readonly onTick?: (state: 'pending' | 'slow_down') => void;
+}
+export declare const SUPPORTED_API_VERSIONS: readonly [3, 2];
+export interface AuthService {
+    /** Probe the auth endpoint, walking `/api/v{n}/auth` then `/auth`. */
+    readonly probe: (apiUrl: string) => Effect.Effect<AuthProbeResult, AuthProbe | NetworkTimeout | NetworkDns | NetworkRefused>;
+    /**
+     * Request a device-code grant. Wave 2 commands drive the full UX flow
+     * (info lines, `open()`, polling). Wave 1 exposes the primitives.
+     */
+    readonly requestDeviceCode: (authBase: string, clientId: string, scope?: string) => Effect.Effect<DeviceCodeResponse, AuthDenied | Generic>;
+    /** Poll the token endpoint until completion or expiry. */
+    readonly pollDeviceToken: (authBase: string, clientId: string, deviceCode: string, opts: PollDeviceTokenOptions) => Effect.Effect<DeviceTokenResponse, AuthDenied | AuthExpired | Generic>;
+    /** Refresh `cred` via either `refresh_token` grant or `get-session`. */
+    readonly refresh: (authBase: string, clientId: string, cred: CredentialsShape) => Effect.Effect<CredentialsShape | null, Generic>;
+    /**
+     * High-level login (placeholder for Wave 2). The Wave 1 contract returns
+     * `Generic` and is intentionally a thin wrapper so command code can
+     * orchestrate UX (banners, `open`, prompts) explicitly.
+     */
+    readonly login: (opts: LoginOptions) => Effect.Effect<CredentialsShape, AuthDenied | AuthExpired | AuthProbe | Generic>;
+    /** Clear credentials for the named profile (or active profile when null). */
+    readonly logout: (name: string | null) => Effect.Effect<void, Generic>;
+    /** Read the active credentials and return whoami summary. */
+    readonly whoami: Effect.Effect<WhoamiInfo, AuthMissing | AuthExpired | Generic>;
+    /** Read auth status without throwing on missing credentials. */
+    readonly status: Effect.Effect<AuthStatusInfo, Generic>;
+    /**
+     * If the active credential is within 60s of expiry, refresh it and
+     * write back via `Config.writeProfileCredentials`. Returns the freshest
+     * credentials, or fails with `AuthMissing` when none are stored.
+     */
+    readonly ensureFresh: (resolved: ResolvedConfig) => Effect.Effect<CredentialsShape, AuthMissing | AuthExpired | Generic>;
+    /**
+     * Fill in `cred.user` via `GET /get-session` when missing, persisting the
+     * enriched credentials. Returns the input unchanged when the user is
+     * already known or when the upstream call fails — never errors.
+     */
+    readonly enrichUser: (profileName: string, authBase: string, cred: CredentialsShape) => Effect.Effect<CredentialsShape, Generic>;
+}
+declare const Auth_base: Context.TagClass<Auth, "Auth", AuthService>;
+export declare class Auth extends Auth_base {
+    /** Build the Auth Layer; depends on `Config` and `HttpClient`. */
+    static Default: Layer.Layer<Auth, never, Config | HttpClient.HttpClient>;
+}
+export declare const isExpiringSoon: (cred: CredentialsShape, bufferMs?: number) => boolean;
+export declare const toCredentials: (resp: DeviceTokenResponse) => CredentialsShape;
+export {};