ask-marcel-office-cli 0.5.5 → 1.0.0

package/dist/infra/auth.d.ts

@@ -2,22 +2,50 @@ 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>>;
     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;
 };
-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,78 @@ 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;
+};
+/**
+ * Combined outcome of capturing BOTH the Teams web client token AND the
+ * elevated M365ChatClient token inside one browser session. Login-fix
+ * round-2 introduced this to fix the user-visible "second browser asks
+ * me to log in again" symptom on federated tenants (LVMH / Okta): the
+ * old flow opened two separate browser sessions, and silent SSO for the
+ * elevated identity wouldn't pick up the cookies just freshly written
+ * by the first session. Capturing both in one context means cookies are
+ * live in memory — no disk-commit-vs-read race, no separate sign-in
+ * prompt for the elevated identity.
+ */
+type BothTokensResult = {
+    readonly teams: BrowserTokenResult | null;
+    readonly elevated: ElevatedTokenResult;
+};
 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>;
+    /**
+     * 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 +87,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 +106,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 +131,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 +160,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, ChromiumLike, ContextLike, ElevatedFailureReason, ElevatedTokenResult, PageLike, PlaywrightLoader, RequestLike, ResponseLike, };

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

@@ -4,19 +4,78 @@ 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>>;
     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;
 };
 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/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/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,6 @@
 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;
+type OutputFormat = 'text' | 'json';
+declare const render: (data: unknown, logger: Logger, format: OutputFormat) => void;
+declare const renderError: (message: string, format: OutputFormat, errorCode?: string) => void;
 export { render, renderError };
+export type { OutputFormat };

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

@@ -1,4 +1,48 @@
 import type { z } from 'zod';
 import type { Command } from './command-types.js';
+import { type ODataKey } from './odata-query.js';
 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>) => Pick<Command, "schema" | "execute">;
+declare const buildElevatedListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>) => 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>) => 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>) => 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>) => 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>) => 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>) => Pick<Command, "schema" | "execute">;
+export { buildCommand, buildElevatedCommand, buildElevatedListCommand, buildElevatedPickODataListCommand, buildFilterSelectListCommand, buildListCommand, buildNoSkipListCommand, buildPickODataListCommand, buildSelectableCommand, };

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

@@ -3,14 +3,80 @@ import type { Result } from '../../domain/result.js';
 import type { GraphClient } from '../../infra/graph-client.js';
 type CommandSchema = z.ZodType;
 type CommandExecute = (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, import('../../infra/graph-client.js').GraphError>>;
-type CommandCategory = 'auth' | 'drive' | 'excel' | 'sharepoint' | 'tasks' | 'mail' | 'notes' | 'user' | 'calendar' | 'contacts' | 'chats' | 'teams' | 'meta';
+type CommandCategory = 'auth' | 'drive' | 'excel' | 'sharepoint' | 'tasks' | 'mail' | 'notes' | 'user' | 'calendar' | 'contacts' | 'chats' | 'teams' | 'meta' | 'lifecycle';
 type CommandHttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
+type CommandOptionAlias = {
+    readonly name: string;
+    readonly key: string;
+};
+/**
+ * Structured type-hint for a CLI flag value. Surfaces in `help-json` so an
+ * LLM can avoid the trial-and-error of "is this an ID or a name?" prose
+ * reading. Optional — populate only where the hint is non-obvious from the
+ * flag name itself.
+ */
+type ArgumentHint = {
+    readonly kind: 'idOrName';
+} | {
+    readonly kind: 'magicValue';
+    readonly values: ReadonlyArray<string>;
+} | {
+    readonly kind: 'a1Address';
+} | {
+    readonly kind: 'iso8601';
+} | {
+    readonly kind: 'graphSubpath';
+};
 type CommandOptionMeta = {
     readonly name: string;
     readonly key: string;
     readonly description: string;
-    readonly required: true;
+    /**
+     * `true` for required flags (the historical default; commander rejects the
+     * invocation if the flag is missing). `false` for optional flags such as the
+     * OData passthrough query parameters (`--top`, `--filter`, …) which
+     * commands accept but do not demand.
+     */
+    readonly required: boolean;
+    /**
+     * Optional secondary spellings of the same flag. Both the canonical
+     * `name` and every alias name are accepted on the command line; values
+     * passed under an alias are normalized to the canonical `key` before
+     * the schema runs. The canonical name is what `--help` shows first.
+     */
+    readonly aliases?: ReadonlyArray<CommandOptionAlias>;
+    /**
+     * Structured value-type hint for LLM consumers. Optional.
+     */
+    readonly argumentHint?: ArgumentHint;
+};
+/**
+ * A positional argument (i.e. NOT a `--flag`). Used today only for the
+ * `docs` lifecycle command (`ask-marcel docs <command>`) but kept as its
+ * own field so the manifest never claims a positional is a flag. An LLM
+ * consumer reading `help-json` can branch on the presence of
+ * `positionalArguments` to know to skip the `--` prefix.
+ */
+type CommandPositionalArgumentMeta = {
+    readonly name: string;
+    readonly required: boolean;
+    readonly description: string;
 };
+/**
+ * How a paginated command produces subsequent pages. Optional — populate
+ * for any command that has `pagination: true`. Lets an LLM tell which
+ * cursor field to feed back to `next-page` (or whether `next-page` is even
+ * applicable, vs `deltaLink`, vs the header-translation case).
+ */
+type PaginationStrategy = 
+/** Standard: `?$top=N&$skip=K` + `@odata.nextLink` cursor. */
+'nextLink'
+/** `?$top=N` + `nextLink` (Graph rejects `$skip` on this endpoint). */
+ | 'nextLinkNoSkip'
+/** Delta endpoints — `nextLink` while paging, `deltaLink` on final page. */
+ | 'deltaLink'
+/** `--top` translated to `Prefer: odata.maxpagesize` header; `$top` rejected as query. */
+ | 'preferMaxPageSize';
 type CommandMeta = {
     readonly summary: string;
     readonly category: CommandCategory;
@@ -18,13 +84,41 @@ type CommandMeta = {
     readonly graphPathTemplate: string;
     readonly graphDocsUrl: string;
     readonly options: ReadonlyArray<CommandOptionMeta>;
+    readonly positionalArguments?: ReadonlyArray<CommandPositionalArgumentMeta>;
     readonly example: string;
     readonly responseShape?: string;
     readonly bodyTemplate?: string;
+    readonly pagination?: true;
+    readonly paginationStrategy?: PaginationStrategy;
+    /**
+     * Graph permission scopes the endpoint requires. The basic Teams web-client
+     * token grants ~30 scopes (run `ask-marcel scopes-check` to see). Commands
+     * with unmet scopes return `403 Forbidden: Missing scope` at the wire. Use
+     * this for pre-flight checks rather than failing on-the-wire. Optional —
+     * populated only on commands where the audit confirmed a scope-failure
+     * path; absent means "should work with the basic Teams token".
+     */
+    readonly scopesRequired?: ReadonlyArray<string>;
+    /**
+     * `true` if the command needs the M365ChatClient elevated token (captured
+     * at login from `m365.cloud.microsoft`, ODSP allow-list). Only 3 commands
+     * today — the historical-version downloads. An LLM should check this
+     * field before invoking; if the elevated capture failed at login, these
+     * commands will time out.
+     */
+    readonly needsElevatedToken?: true;
+    /**
+     * `true` if the command returns inlined bytes (`{contentType, size, base64}`
+     * or `{contentType, size, text}`) and is therefore a valid target for the
+     * global `--output-path` flag. Used by the CLI composition to derive the
+     * rejection-message whitelist from the manifest rather than hand-keeping it
+     * as a string literal. Audit round-8 Wave E2.
+     */
+    readonly producesBytes?: true;
 };
 type Command = {
     readonly schema: CommandSchema;
     readonly execute: CommandExecute;
     readonly meta: CommandMeta;
 };
-export type { Command, CommandCategory, CommandExecute, CommandHttpMethod, CommandMeta, CommandOptionMeta, CommandSchema };
+export type { ArgumentHint, Command, CommandCategory, CommandExecute, CommandHttpMethod, CommandMeta, CommandOptionAlias, CommandOptionMeta, CommandPositionalArgumentMeta, CommandSchema, PaginationStrategy, };

package/dist/use-cases/commands/convert-mail-attachment-to-markdown.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    messageId: z.ZodString;
+    attachmentId: z.ZodString;
+}, z.core.$strip>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/convert-mail-attachment-to-pdf.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    messageId: z.ZodString;
+    attachmentId: z.ZodString;
+}, z.core.$strip>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/convert-mail-to-markdown.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    messageId: z.ZodString;
+}, z.core.$strip>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/docs-render.d.ts

@@ -7,10 +7,17 @@ export type CommandManifestEntry = {
     readonly graphPathTemplate: string;
     readonly graphDocsUrl: string;
     readonly options: CommandMeta['options'];
+    readonly positionalArguments?: CommandMeta['positionalArguments'];
     readonly example: string;
     readonly responseShape?: string;
     readonly bodyTemplate?: string;
+    readonly pagination?: true;
+    readonly paginationStrategy?: CommandMeta['paginationStrategy'];
+    readonly scopesRequired?: CommandMeta['scopesRequired'];
+    readonly needsElevatedToken?: CommandMeta['needsElevatedToken'];
+    readonly producesBytes?: CommandMeta['producesBytes'];
 };
+export declare const PAGINATION_HINT = "Paginated by Microsoft Graph. The CLI hoists `@odata.nextLink` out of `data` to the **top-level `nextLink`** field of the response envelope (and `@odata.deltaLink` to top-level `deltaLink` for delta commands). Pass that URL to `next-page --url <link>` and repeat until the field is absent. Do NOT look for `data[\"@odata.nextLink\"]` \u2014 the presenter strips it from `data` so the cursor is always at envelope level.";
 export type CommandManifest = {
     readonly package: string;
     readonly version: string;

package/dist/use-cases/commands/docx-to-markdown.d.ts

@@ -0,0 +1,11 @@
+import type { Result } from '../../domain/result.js';
+import type { GraphError } from '../../infra/graph-client.js';
+type MarkdownEnvelope = {
+    readonly contentType: 'text/markdown';
+    readonly size: number;
+    readonly text: string;
+};
+declare const promoteFirstRowToThead: (html: string) => string;
+declare const docxToMarkdown: (bytes: Uint8Array) => Promise<Result<MarkdownEnvelope, GraphError>>;
+export { docxToMarkdown, promoteFirstRowToThead };
+export type { MarkdownEnvelope };

package/dist/use-cases/commands/download-drive-item-as-markdown.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    driveId: z.ZodString;
+    itemId: z.ZodString;
+}, z.core.$strip>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/download-drive-item-as-pdf.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    driveId: z.ZodString;
+    itemId: z.ZodString;
+}, z.core.$strip>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/download-drive-item-version-as-markdown.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    driveId: z.ZodString;
+    itemId: z.ZodString;
+    versionId: z.ZodString;
+}, z.core.$strip>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/download-drive-item-version-as-pdf.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    driveId: z.ZodString;
+    itemId: z.ZodString;
+    versionId: z.ZodString;
+}, z.core.$strip>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/download-onedrive-file-content.d.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 import type { Result } from '../../domain/result.js';
-import type { GraphClient } from '../../infra/graph-client.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
 import type { CommandMeta } from './command-types.js';
 declare const schema: z.ZodObject<{
     driveId: z.ZodString;
     itemId: z.ZodString;
 }, z.core.$strip>;
-declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, import("../../infra/graph-client.js").GraphError>>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
 declare const meta: CommandMeta;
 export { execute, meta, schema };