ask-marcel-office-cli 0.5.5 → 1.4.0

package/dist/infra/auth.d.ts

@@ -2,22 +2,80 @@ import type { AccessToken } from '../domain/access-token.js';
 import type { Result } from '../domain/result.js';
 import type { FileSystem } from '../use-cases/ports/filesystem.js';
 import type { Logger } from '../use-cases/ports/logger.js';
-import type { BrowserAuth } from './browser-auth.js';
+import type { BrowserAuth, ElevatedFailureReason } from './browser-auth.js';
 type AuthError = {
     type: 'auth_failed';
     message: string;
 } | {
     type: 'auth_cancelled';
 };
+/**
+ * Outcome of the elevated-token capture leg of the most recent
+ * browser-acquired session. Read by `login.execute` to surface a
+ * `{ elevated: 'captured' | 'failed', elevatedReason?: ... }` field on
+ * the login response so an LLM consumer can predict whether the
+ * elevated-dependent commands (chat metadata, historical-version
+ * downloads) will work without invoking them. Login-fix round-1 Wave D.
+ */
+type ElevatedOutcome = {
+    captured: true;
+} | {
+    captured: false;
+    reason: ElevatedFailureReason | 'unknown_error';
+};
 type AuthManager = {
     getAccessToken: () => Promise<Result<AccessToken, AuthError>>;
+    /**
+     * Returns a Graph token issued for an app on Microsoft's ODSP
+     * `logicalPermissions` allow-list. Falls through cache → re-capture
+     * via headless Playwright. Used by the 3 historical-version commands.
+     */
+    getElevatedAccessToken: () => Promise<Result<AccessToken, AuthError>>;
+    /**
+     * Returns a chatsvcagg-audience token (same Teams web client identity
+     * as `getAccessToken`, but issued for the chatsvcagg resource). Falls
+     * through cache → re-capture via headless Playwright. Used by the
+     * `list-teams-chats-with-messages` family of commands.
+     */
+    getChatsvcaggAccessToken: () => Promise<Result<AccessToken, AuthError>>;
+    /**
+     * Returns the regional segment used to construct chatsvcagg substrate
+     * URLs (`teams.microsoft.com/api/csa/<region>/api/...`). Captured at
+     * login from the first such URL the chatsvcagg bearer rides on. Falls
+     * back to `DEFAULT_CHATSVCAGG_REGION` ('emea') when the cache is
+     * either absent or pre-2026-05-migration. Synchronous on cache; calls
+     * `getChatsvcaggAccessToken()` first if no cache exists so a region is
+     * available immediately after login.
+     */
+    getChatsvcaggRegion: () => Promise<string>;
+    /**
+     * Returns an IC3-audience bearer (Teams web client identity, aud
+     * `https://ic3.teams.office.com`). Falls through cache → re-capture
+     * via headless Playwright. Used by `list-teams-chat-history` to walk
+     * paginated chat-message history beyond the 200-message chatsvcagg cap.
+     */
+    getIc3AccessToken: () => Promise<Result<AccessToken, AuthError>>;
     logout: () => Promise<Result<void, AuthError>>;
+    /**
+     * Inspect the elevated-capture outcome from the most recent
+     * `acquireViaBrowser` invocation. Returns null if no browser-acquired
+     * session has happened in this process (cache hit / refresh-only).
+     * Login-fix round-1 Wave D.
+     */
+    getLastElevatedOutcome: () => ElevatedOutcome | null;
+    /**
+     * Inspect the chatsvcagg-capture outcome from the most recent
+     * `acquireViaBrowser` invocation. Same shape and lifetime semantics
+     * as `getLastElevatedOutcome`.
+     */
+    getLastChatsvcaggOutcome: () => ElevatedOutcome | null;
 };
-declare const createAuthManagerFromApi: (browserAuth: BrowserAuth, cachePath: string, logger: Logger, fs: FileSystem) => AuthManager;
+declare const createAuthManagerFromApi: (browserAuth: BrowserAuth, cachePath: string, browserProfileDir: string, logger: Logger, fs: FileSystem) => AuthManager;
 declare const createAuthManager: (deps: {
     cachePath: string;
     logger: Logger;
     fs?: FileSystem;
+    browserProfileDir?: string;
 }) => AuthManager;
 export { createAuthManager, createAuthManagerFromApi };
-export type { AuthError, AuthManager };
+export type { AuthError, AuthManager, ElevatedOutcome };

package/dist/infra/browser-auth.d.ts

@@ -5,8 +5,143 @@ type BrowserTokenResult = {
     accessToken: AccessToken;
     refreshToken: string | null;
 };
+/**
+ * Discriminated outcome of an elevated-token capture attempt. Distinct
+ * failure variants let the caller pick the right error message AND let
+ * the auto-heal in auth.ts decide whether a retry is worthwhile (a
+ * recoverable failure like `launch_timeout` or `sso_timeout` is worth
+ * one retry after wiping the profile; `navigation_failed` is a network
+ * issue, not worth retrying).
+ *
+ * Login-fix round-1: was previously `AccessToken | null`, which conflated
+ * "browser launch hung", "navigation broke", and "silent-SSO polling
+ * timed out" into a single null and made the error message inaccurate.
+ */
+type ElevatedFailureReason = 'launch_timeout' | 'navigation_failed' | 'sso_timeout';
+type ElevatedTokenResult = {
+    readonly ok: true;
+    readonly token: AccessToken;
+} | {
+    readonly ok: false;
+    readonly reason: ElevatedFailureReason;
+};
+/**
+ * chatsvcagg capture result. Carries the same three failure modes as
+ * `ElevatedTokenResult` PLUS the parsed regional segment from the URL
+ * the bearer rode on (`emea` / `amer` / `apac` / etc.) — the new
+ * substrate host (`teams.microsoft.com/api/csa/<region>/api/...`) routes
+ * per region, so callers must persist this alongside the token to
+ * construct future URLs. See `gotcha_chatsvcagg_substrate_moved` in
+ * the project memory for the 2026-05 migration that made this
+ * necessary.
+ */
+type ChatsvcaggTokenResult = {
+    readonly ok: true;
+    readonly token: AccessToken;
+    readonly region: string;
+} | {
+    readonly ok: false;
+    readonly reason: ElevatedFailureReason;
+};
+/**
+ * IC3 capture result. The "next-gen" Teams chat-message substrate at
+ * `teams.microsoft.com/api/chatsvc/<region>/v1/users/ME/conversations/{id}/messages`
+ * — the path Teams web actually uses for chat scrollback (the existing
+ * chatsvcagg substrate at `/api/csa/<region>/api/v1/chats/{id}/messages`
+ * is the chat-list aggregator and caps at the 200 most recent messages
+ * with no working pagination cursor). The IC3 path supports `syncState`
+ * + `startTime` pagination, unlocking arbitrary-depth chat history.
+ *
+ * Bearer audience: `https://ic3.teams.office.com`. Standard `Bearer`
+ * authorization (NOT the purple-teams-documented `skype_token X`
+ * header — those forks predate Teams' move to OAuth bearer on this
+ * surface). Empirically discovered 2026-05-21 by widening the
+ * Playwright capture listener.
+ */
+type Ic3TokenResult = {
+    readonly ok: true;
+    readonly token: AccessToken;
+    readonly region: string;
+} | {
+    readonly ok: false;
+    readonly reason: ElevatedFailureReason;
+};
+/**
+ * Combined outcome of capturing all four tokens (Teams basic / M365
+ * elevated / chatsvcagg substrate / IC3 substrate) inside one browser
+ * session. Login-fix round-2 introduced this for the basic+elevated
+ * pair; chatsvcagg was added next; IC3 is the most recent leg, capturing
+ * the bearer Teams web uses for unbounded chat-history reads.
+ *
+ * All four legs ride on the SAME `teams.microsoft.com` session, so
+ * adding capture legs is essentially free — MSAL multiplexes the
+ * audience-scoped bearers via silent acquisition.
+ */
+type BothTokensResult = {
+    readonly teams: BrowserTokenResult | null;
+    readonly elevated: ElevatedTokenResult;
+    readonly chatsvcagg: ChatsvcaggTokenResult;
+    readonly ic3: Ic3TokenResult;
+};
 type BrowserAuth = {
     acquireToken: (scopes: string[], startUrl: string) => Promise<BrowserTokenResult | null>;
+    /**
+     * Capture an "elevated" Graph access token by navigating to a
+     * different Microsoft web app whose first-party app identity is on
+     * Microsoft's allow-list for ODSP `logicalPermissions` (the scope our
+     * Teams web client token lacks for historical-version stream
+     * content). Reuses the persistent profile cookies — no second
+     * sign-in. Headless by default.
+     *
+     * Returns a discriminated union so the caller can distinguish the three
+     * failure modes (browser-launch hang, navigation failure, silent-SSO
+     * polling timeout). The caller decides whether the failure is fatal
+     * (it isn't for most commands; only the version + chat commands need
+     * this).
+     *
+     * Standalone fallback path: used by `getElevatedAccessToken` when the
+     * cached elevated token expires and the Teams session is already in
+     * the cache (no fresh sign-in needed). On `login`, use
+     * `acquireBothTokens` instead so the user sees only one browser.
+     */
+    acquireElevatedToken: () => Promise<ElevatedTokenResult>;
+    /**
+     * Capture a chatsvcagg-audience bearer (Teams basic identity, but the
+     * `chatsvcagg.teams.microsoft.com` resource instead of Graph) by
+     * navigating headless to `teams.microsoft.com/v2/`. The persistent
+     * profile's SSO cookies do the auth silently. Used by
+     * `getChatsvcaggAccessToken()` when the cached chatsvcagg token has
+     * expired and the basic Teams session is still warm.
+     *
+     * Same failure-mode shape as `acquireElevatedToken` — launch hang,
+     * navigation failure, silent SSO timeout — so the auth-manager can
+     * reuse the same auto-heal logic.
+     */
+    acquireChatsvcaggToken: () => Promise<ChatsvcaggTokenResult>;
+    /**
+     * Capture an IC3-audience bearer (aud `https://ic3.teams.office.com`,
+     * same basic Teams appid). The bearer Teams web client uses to call
+     * `teams.microsoft.com/api/chatsvc/<region>/v1/users/ME/conversations/{id}/messages`
+     * — the chat-message substrate with proper `syncState` pagination,
+     * enabling reads beyond the 200-message chatsvcagg cap. Same failure
+     * modes as `acquireChatsvcaggToken`.
+     */
+    acquireIc3Token: () => Promise<Ic3TokenResult>;
+    /**
+     * Login-fix round-2: capture BOTH tokens inside ONE browser session.
+     * After the Teams response listener intercepts the Teams token,
+     * navigate the SAME page to the elevated URL and harvest the
+     * M365ChatClient bearer from outgoing request headers. Cookies are
+     * live in memory, so federated SSO chains (e.g. Okta-fronted
+     * tenants) work without a second visible sign-in.
+     *
+     * Returns `teams: null` if no Teams token came back within the full
+     * `pollDeadlineMs` (5 min). Returns
+     * `elevated: { ok: false, reason: ... }` if the elevated capture
+     * failed inside the same session — caller decides whether to surface
+     * the partial success.
+     */
+    acquireBothTokens: (scopes: string[], teamsUrl: string) => Promise<BothTokensResult>;
     close: () => Promise<void>;
 };
 type ResponseLike = {
@@ -17,6 +152,7 @@ type ResponseLike = {
 type ResponseHandler = (response: ResponseLike) => void;
 type PageLike = {
     on(event: 'response', handler: ResponseHandler): void;
+    on(event: 'request', handler: RequestHandler): void;
     goto(url: string, options: {
         waitUntil: 'domcontentloaded';
         timeout: number;
@@ -35,6 +171,11 @@ type LaunchOptions = {
     channel?: 'msedge' | 'chrome';
     args: string[];
 };
+type RequestLike = {
+    url(): string;
+    headers(): Record<string, string>;
+};
+type RequestHandler = (request: RequestLike) => void;
 type BrowserAuthApi = {
     launchPersistentContext(profileDir: string, options: LaunchOptions): Promise<ContextLike>;
 };
@@ -55,6 +196,27 @@ type BrowserAuthConfig = {
     readonly pollIntervalMs?: number;
     readonly pollDeadlineMs?: number;
     readonly navigationTimeoutMs?: number;
+    /**
+     * Deadline for the SILENT elevated-token recapture flow (no user
+     * interaction expected — persistent profile cookies do the SSO).
+     * Defaults to 20s. The audit (v1.0.0 §1.1) flagged that reusing the
+     * 5-minute interactive `pollDeadlineMs` for this silent path made
+     * `list-chats` etc. hang for minutes when cookies were stale, blowing
+     * the LLM tool-call window. With a tight cap, the flow either yields
+     * a token quickly or fails with `auth_failed: elevated token capture
+     * timed out — run `ask-marcel login` to refresh.`
+     */
+    readonly elevatedRecaptureTimeoutMs?: number;
+    /**
+     * Hard deadline on `launchPersistentContext` + `newPage` for the
+     * elevated capture path. Defaults to 15s. Distinct from
+     * `elevatedRecaptureTimeoutMs` so the error message can name which
+     * step hung — launch vs polling. Audit login-fix round-1: previously
+     * unguarded, so a hung Playwright launch (corrupt persistent profile
+     * with stale `Singleton*` locks, or a slow browser binary) would
+     * block the whole command indefinitely.
+     */
+    readonly elevatedLaunchTimeoutMs?: number;
 };
 declare const createPlaywrightApi: (loader: PlaywrightLoader) => BrowserAuthApi;
 declare const createBrowserAuthFromApi: (api: BrowserAuthApi, config: BrowserAuthConfig) => BrowserAuth;
@@ -63,4 +225,4 @@ declare const createBrowserAuth: (deps: {
     fs?: FileSystem;
 }) => BrowserAuth;
 export { createBrowserAuth, createBrowserAuthFromApi, createPlaywrightApi };
-export type { BrowserAuth, BrowserAuthApi, BrowserAuthConfig, BrowserTokenResult, ChromiumLike, ContextLike, PageLike, PlaywrightLoader, ResponseLike };
+export type { BothTokensResult, BrowserAuth, BrowserAuthApi, BrowserAuthConfig, BrowserTokenResult, ChatsvcaggTokenResult, Ic3TokenResult, ChromiumLike, ContextLike, ElevatedFailureReason, ElevatedTokenResult, PageLike, PlaywrightLoader, RequestLike, ResponseLike, };

package/dist/infra/graph-client.d.ts

@@ -4,19 +4,116 @@ type GraphError = {
     type: 'api_error';
     status: number;
     message: string;
+    code?: string;
 } | {
     type: 'auth_failed';
     message: string;
+    code?: string;
 } | {
     type: 'network_error';
     message: string;
+    code?: string;
+} | {
+    type: 'validation_error';
+    message: string;
+    code?: string;
 };
 type GraphClient = {
-    get: (path: string) => Promise<Result<unknown, GraphError>>;
+    /**
+     * `extraHeaders` lets a caller add request headers Graph requires on
+     * specific endpoints — currently the only documented use is
+     * `Prefer: odata.maxpagesize=N` on the calendar/mail delta endpoints,
+     * which reject `$top` as a query parameter. Auth + content-type are
+     * always set internally.
+     */
+    get: (path: string, extraHeaders?: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+    /**
+     * Same JSON-GET shape as `get`, but signs the request with the
+     * elevated Graph token (M365ChatClient). Used by commands the Teams
+     * web client token cannot reach — currently `list-chats` and
+     * `get-chat`, which need `Chat.ReadBasic` (only present on the
+     * elevated token).
+     */
+    getElevated: (path: string) => Promise<Result<unknown, GraphError>>;
+    /**
+     * JSON-GET against the Teams chat substrate (post-2026-05:
+     * `teams.microsoft.com/api/csa/<region>/api/v{N}/...` — see
+     * `gotcha_chatsvcagg_substrate_moved` in memory for the migration
+     * away from `chatsvcagg.teams.microsoft.com`). Signs the request
+     * with the chatsvcagg-audience bearer captured at login (same Teams
+     * web client identity as `get`, different audience), and injects the
+     * cached substrate region between the host and `path`. Used by
+     * commands that need to read chat message BODIES, which the basic
+     * Graph token cannot reach (`Chat.Read*` scopes are missing).
+     *
+     * `path` MUST start with `/api/v{N}/...` — the host + `/api/csa/<region>`
+     * prefix are added by this client.
+     */
+    teamsChat: (path: string) => Promise<Result<unknown, GraphError>>;
+    /**
+     * JSON-GET against the Teams IC3 chat-message substrate at
+     * `teams.microsoft.com/api/chatsvc/<region>/v1/...`. Same host as
+     * `teamsChat` but a DIFFERENT path prefix AND a different bearer
+     * audience (`https://ic3.teams.office.com` instead of
+     * `https://chatsvcagg.teams.microsoft.com`). The path supports
+     * `syncState` + `startTime` pagination — unlocking arbitrary-depth
+     * chat-history reads beyond the chatsvcagg 200-message cap (see
+     * `gotcha_chatsvcagg_substrate_moved` in memory). Used by
+     * `list-teams-chat-history`.
+     *
+     * `path` MUST start with `/v1/...` (e.g. `/v1/users/ME/conversations/{id}/messages?startTime=...`)
+     * — the host + `/api/chatsvc/<region>` prefix are added here.
+     */
+    teamsChatIc3: (path: string) => Promise<Result<unknown, GraphError>>;
     post: (path: string, body: unknown) => Promise<Result<unknown, GraphError>>;
     getBinary: (path: string) => Promise<Result<unknown, GraphError>>;
+    /**
+     * Same shape as `getBinary` but signs the request with an "elevated"
+     * Graph token (issued for an app on Microsoft's ODSP
+     * `logicalPermissions` allow-list — e.g., M365ChatClient). Used by
+     * the historical-version commands which the Teams web client token
+     * cannot fetch (403 logicalPermissionAccessDenied).
+     */
+    getBinaryElevated: (path: string) => Promise<Result<unknown, GraphError>>;
+    /**
+     * Auth-less fetch of an arbitrary URL whose host MUST be on the
+     * Microsoft allow-list. Used to follow `@microsoft.graph.downloadUrl`
+     * 302 redirects (CDN-signed URLs) that the format-conversion
+     * commands sometimes get back from Graph instead of inline bytes.
+     */
+    fetchUrl: (url: string) => Promise<Result<unknown, GraphError>>;
+    /**
+     * Upload bytes to a drive item. `basePath` is the bare driveItem
+     * path (e.g. `/me/drive/root:/.ask-marcel-temp/abc.rtf`) — `put()`
+     * appends `:/content` for the simple ≤4 MiB sync path or
+     * `:/createUploadSession` for the chunked-session path internally
+     * based on `body.byteLength`. No upper file-size limit beyond the
+     * user's OneDrive quota.
+     */
+    put: (basePath: string, body: Uint8Array, contentType?: string) => Promise<Result<unknown, GraphError>>;
+    delete: (path: string) => Promise<Result<unknown, GraphError>>;
+    /**
+     * Decode the cached basic Teams token's JWT and return its scopes /
+     * audience / expiry. Used by the `scopes-check` self-test command so the
+     * LLM can predict `accessDenied` instead of discovering it on the next
+     * Graph call. No network IO — operates on the cached token only.
+     */
+    getCachedTokenInfo: () => Promise<Result<TokenInfo, GraphError>>;
+};
+type TokenInfo = {
+    readonly scopes: ReadonlyArray<string>;
+    readonly audience: string | undefined;
+    readonly expiresAt: string | undefined;
+    /**
+     * Seconds remaining until the cached token's `exp` claim — derived from
+     * `expiresAt - now`. Negative when the token has already expired. Absent
+     * when the JWT did not carry an `exp` claim. Audit Hervé-session §4: lets
+     * an LLM decide pre-emptively to run `ask-marcel login` (re-auth typically
+     * worth doing under ~5 minutes) without parsing the ISO string itself.
+     */
+    readonly expiresInSeconds: number | undefined;
 };
 type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
 declare const createGraphClient: (auth: AuthManager, fetchFn?: FetchFn) => GraphClient;
 export { createGraphClient };
-export type { FetchFn, GraphClient, GraphError };
+export type { FetchFn, GraphClient, GraphError, TokenInfo };

package/dist/infra/mammoth-adapter.d.ts

@@ -0,0 +1,4 @@
+import type { Result } from '../domain/result.js';
+import type { GraphError } from './graph-client.js';
+declare const mammothToHtml: (bytes: Uint8Array) => Promise<Result<string, GraphError>>;
+export { mammothToHtml };

package/dist/infra/network-error.d.ts

@@ -0,0 +1,9 @@
+export declare const REQUEST_TIMEOUT_MS = 60000;
+export declare const BINARY_TRANSFER_TIMEOUT_MS: number;
+export declare const REQUEST_TIMEOUT_LABEL = "60s";
+export declare const BINARY_TRANSFER_TIMEOUT_LABEL = "5min";
+export declare const networkErrorMessage: (e: unknown, label: string, timeoutLabel: string) => string;
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+export type TimeoutTier = 'json' | 'binary';
+export declare const timeoutLabelFor: (tier: TimeoutTier) => string;
+export declare const timeoutMsFor: (tier: TimeoutTier) => number;

package/dist/infra/sheetjs-adapter.d.ts

@@ -0,0 +1,9 @@
+import type { Result } from '../domain/result.js';
+import type { GraphError } from './graph-client.js';
+type SheetCsv = {
+    readonly name: string;
+    readonly csv: string;
+};
+declare const readSheetsAsCsv: (bytes: Uint8Array) => Result<ReadonlyArray<SheetCsv>, GraphError>;
+export { readSheetsAsCsv };
+export type { SheetCsv };

package/dist/infra/turndown-adapter.d.ts

@@ -0,0 +1,4 @@
+import type { Result } from '../domain/result.js';
+import type { GraphError } from './graph-client.js';
+declare const htmlToMarkdown: (html: string) => Result<string, GraphError>;
+export { htmlToMarkdown };

package/dist/presenter/error-hints.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Translate Graph / substrate / CLI / validation errors into actionable hints.
+ *
+ * Audit Hervé-session §2: bare `error: ErrorInvalidIdMalformed: Id is
+ * malformed.` had no remedy for the LLM — it had to guess where the bad ID
+ * came from. This module is the centralised "what should I do about this"
+ * lookup: pattern-match the error code (or, as a fallback, a substring of
+ * the message) and surface a one-line hint plus a `source` classifier so
+ * the LLM can branch on whether the failure is server-side, substrate-side,
+ * CLI-side, or a Zod validation rejection. Surfaced through the standard
+ * error envelope in both `--output json` (as `hint` / `source` fields) and
+ * `--output text` (as `hint:` / `source:` lines under the existing `error:`
+ * line).
+ *
+ * Audit Hervé-session §2 follow-up: the four error-envelope variants are
+ *   - `graph`      — public Microsoft Graph API at /v1.0/
+ *   - `substrate`  — Microsoft-internal chat substrates (chatsvcagg / IC3).
+ *                    Tagged at the infra layer with `substrateHttp{N}_{name}`.
+ *   - `cli`        — CLI itself (Commander parser, CLI rewrites of Graph
+ *                    errors via `cli_rewrite_*` and `cli_reject_*` codes)
+ *   - `validation` — Zod schema validation from use-cases (no `code` — pure
+ *                    message-pattern fallback)
+ *
+ * Rule precedence: specific code matchers run FIRST, then message-pattern
+ * fallbacks. The generic-validation rule sits LAST so it never overrides a
+ * code-based remedy.
+ *
+ * The table is intentionally small and biased toward HIGH-FREQUENCY errors
+ * an LLM actually hits. Adding more entries is cheap; the lookup is O(n)
+ * on a tiny n.
+ */
+export type ErrorSource = 'graph' | 'substrate' | 'cli' | 'validation';
+export type ErrorHint = {
+    readonly hint: string;
+    readonly source: ErrorSource;
+};
+/**
+ * First matching rule wins. Returns `undefined` when nothing in the table
+ * matches — caller renders the bare error (the historical shape).
+ */
+export declare const findErrorHint: (message: string, code: string | undefined) => ErrorHint | undefined;

package/dist/presenter/output-text.d.ts

@@ -0,0 +1,2 @@
+declare const renderTextOutput: (data: unknown) => string;
+export { renderTextOutput };

package/dist/presenter/output.d.ts

@@ -1,4 +1,7 @@
 import type { Logger } from '../use-cases/ports/logger.js';
-declare const render: (data: unknown, logger: Logger) => void;
-declare const renderError: (message: string, logger: Logger) => void;
+import type { ErrorSource } from './error-hints.js';
+type OutputFormat = 'text' | 'json';
+declare const render: (data: unknown, logger: Logger, format: OutputFormat) => void;
+declare const renderError: (message: string, format: OutputFormat, errorCode?: string, explicitSource?: ErrorSource) => void;
 export { render, renderError };
+export type { OutputFormat };

package/dist/use-cases/commands/build-command.d.ts

@@ -1,4 +1,70 @@
 import type { z } from 'zod';
 import type { Command } from './command-types.js';
+import { type ODataKey } from './odata-query.js';
+/**
+ * Options accepted by every builder that knows about `$select` (i.e. every
+ * builder except `buildCommand` / `buildElevatedCommand`, which take no OData
+ * passthroughs at all). `defaultSelect`, when set and the user did NOT pass
+ * `--select`, is injected into the OData query string so default invocations
+ * return a slim projection instead of a 50 KB resource. User-supplied
+ * `--select` always wins. Audit Hervé-session §A: pairs the `list-mail-attachments`
+ * pattern with the builder layer so the 6 heaviest endpoints stop returning
+ * the full Graph resource by default.
+ */
+type SelectDefaults = {
+    readonly defaultSelect?: string;
+};
 declare const buildCommand: (pathFn: (params: Record<string, string>) => string, schema: z.ZodType) => Pick<Command, "schema" | "execute">;
-export { buildCommand };
+declare const buildElevatedCommand: (pathFn: (params: Record<string, string>) => string, schema: z.ZodType) => Pick<Command, "schema" | "execute">;
+declare const buildListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+declare const buildElevatedListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+/**
+ * Single-resource GET that supports the OData `$select` and `$expand` query
+ * parameters. Mirrors `buildListCommand` but exposes only the two flags that
+ * make sense on a non-paginated resource — no `$top`/`$skip`/`$filter`/
+ * `$orderby` since there's no collection to slice. Lets an LLM ask only for
+ * the fields it needs (e.g. `--select id,subject`) instead of swallowing a
+ * 50 KB resource just to read a subject line.
+ */
+declare const buildSelectableCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+/**
+ * Elevated-token twin of `buildSelectableCommand`. Use for single-resource
+ * GETs on endpoints that require the M365ChatClient identity (e.g. `/chats/{id}`)
+ * AND benefit from `$select`/`$expand` projection. The basic `buildElevatedCommand`
+ * builder takes no OData passthroughs — use this when the endpoint honours
+ * field projection, so an LLM can avoid pulling the whole resource just to
+ * read a topic or chatType.
+ */
+declare const buildElevatedSelectableCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+/**
+ * Collection GET that supports ONLY `$filter` and `$select` — for endpoints
+ * Microsoft documents as rejecting the other OData passthroughs (`/teams/{id}/channels`
+ * is the canonical case: Graph returns BadRequest on `$top`, `$skip`, `$orderby`,
+ * `$expand`). Advertising the unsupported flags would be a usability lie.
+ */
+declare const buildFilterSelectListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+/**
+ * Collection GET on an endpoint that supports the usual OData passthroughs
+ * EXCEPT `$skip` (e.g. `/me/drive/recent`, `/sites/{id}/lists`,
+ * `/me/drive/search`). Graph rejects `$skip` with
+ * `invalidRequest: $skip is not supported on this API.`; the CLI mirrors
+ * by dropping `--skip` from the advertised flag set.
+ */
+declare const buildNoSkipListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+/**
+ * Collection GET that supports an EXPLICIT subset of OData passthroughs.
+ * Use for endpoints where Graph silently drops some flags — passing
+ * `keys: ['top', 'select']` advertises only `--top` and `--select` and
+ * keeps the manifest honest. The other narrower builders
+ * (`buildNoSkipListCommand`, `buildFilterSelectListCommand`) are
+ * specializations; this is the generic escape hatch.
+ */
+declare const buildPickODataListCommand: <Shape extends z.ZodRawShape, K extends ODataKey>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, keys: ReadonlyArray<K>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+/**
+ * Elevated-token twin of `buildPickODataListCommand`. Use for endpoints that
+ * require the M365ChatClient identity (e.g. `/me/chats`, `/chats/{}/members`)
+ * AND honour only a subset of OData passthroughs — the chats family rejects
+ * `$orderby` / `$expand` with `BadRequest`, so the picker is the right tool.
+ */
+declare const buildElevatedPickODataListCommand: <Shape extends z.ZodRawShape, K extends ODataKey>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, keys: ReadonlyArray<K>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+export { buildCommand, buildElevatedCommand, buildElevatedListCommand, buildElevatedPickODataListCommand, buildElevatedSelectableCommand, buildFilterSelectListCommand, buildListCommand, buildNoSkipListCommand, buildPickODataListCommand, buildSelectableCommand, };