ask-marcel-office-cli 1.4.0 → 1.5.0

package/dist/infra/auth.d.ts

@@ -70,12 +70,35 @@ type AuthManager = {
      */
     getLastChatsvcaggOutcome: () => ElevatedOutcome | null;
 };
-declare const createAuthManagerFromApi: (browserAuth: BrowserAuth, cachePath: string, browserProfileDir: string, logger: Logger, fs: FileSystem) => AuthManager;
+type SystemBrowserAuthFn = () => Promise<Result<{
+    accessToken: AccessToken;
+    refreshToken: string | null;
+    elevatedAccessToken?: AccessToken | null;
+    chatsvcaggAccessToken?: AccessToken | null;
+    ic3AccessToken?: AccessToken | null;
+    chatsvcaggRegion?: string;
+}, {
+    type: string;
+    message: string;
+}>>;
+declare const createAuthManagerFromApi: (browserAuth: BrowserAuth, cachePath: string, browserProfileDir: string, logger: Logger, fs: FileSystem, systemBrowserAuthFn?: SystemBrowserAuthFn, usePlaywrightFallback?: boolean, skipSystemBrowser?: boolean) => AuthManager;
+/**
+ * QA-010: probe the token cache for a fresh access token. Handed to the
+ * browser capture so its poll loop can short-circuit the multi-minute dance
+ * when a concurrent process refreshes first (AAD rotates SPA refresh tokens,
+ * so the loser of the race cannot refresh and falls into the browser leg).
+ * Exported for the composition test; pure read, never writes.
+ */
+declare const createFreshCachedTokenProbe: (fs: FileSystem, cachePath: string) => (() => Promise<string | null>);
+declare const stderrProgress: (line: string) => void;
 declare const createAuthManager: (deps: {
     cachePath: string;
     logger: Logger;
     fs?: FileSystem;
     browserProfileDir?: string;
+    systemBrowserAuth?: SystemBrowserAuthFn;
+    usePlaywrightFallback?: boolean;
+    skipSystemBrowser?: boolean;
 }) => AuthManager;
-export { createAuthManager, createAuthManagerFromApi };
-export type { AuthError, AuthManager, ElevatedOutcome };
+export { createAuthManager, createAuthManagerFromApi, createFreshCachedTokenProbe, stderrProgress };
+export type { AuthError, AuthManager, ElevatedOutcome, SystemBrowserAuthFn };

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

@@ -82,6 +82,14 @@ type BothTokensResult = {
     readonly elevated: ElevatedTokenResult;
     readonly chatsvcagg: ChatsvcaggTokenResult;
     readonly ic3: Ic3TokenResult;
+    /**
+     * Set when the Teams poll short-circuited because `freshCachedToken`
+     * found a token written by a concurrent process (QA-010). The caller
+     * must NOT persist this result — the cache is already the source of
+     * truth, and `refreshToken` is null here (persisting would clobber the
+     * winner's rotated refresh token).
+     */
+    readonly fromCache?: true;
 };
 type BrowserAuth = {
     acquireToken: (scopes: string[], startUrl: string) => Promise<BrowserTokenResult | null>;
@@ -190,6 +198,21 @@ type BrowserAuthConfig = {
     readonly logger: Logger;
     readonly fs: FileSystem;
     readonly trace?: TraceFn;
+    /**
+     * QA-010 (login hang): probe for a fresh token that landed in the cache
+     * WHILE the browser capture is polling. AAD SPA refresh tokens rotate, so
+     * when two processes race, the loser's refresh fails and it falls into the
+     * full multi-minute browser dance — while the winner's fresh token sits in
+     * the cache the whole time. The Teams poll loop calls this every interval
+     * and short-circuits (closing the browser) the moment it returns a token.
+     */
+    readonly freshCachedToken?: () => Promise<string | null>;
+    /**
+     * User-visible progress sink (stderr in production). The browser capture
+     * can legitimately take minutes (federated SSO, interactive sign-in); these
+     * one-liners are what separates "waiting on the user" from "hung" (QA-010).
+     */
+    readonly onProgress?: (line: string) => void;
     readonly profileDir?: string;
     readonly initialSettleMs?: number;
     readonly postReloginSettleMs?: number;
@@ -223,6 +246,8 @@ declare const createBrowserAuthFromApi: (api: BrowserAuthApi, config: BrowserAut
 declare const createBrowserAuth: (deps: {
     logger: Logger;
     fs?: FileSystem;
+    freshCachedToken?: () => Promise<string | null>;
+    onProgress?: (line: string) => void;
 }) => BrowserAuth;
 export { createBrowserAuth, createBrowserAuthFromApi, createPlaywrightApi };
 export type { BothTokensResult, BrowserAuth, BrowserAuthApi, BrowserAuthConfig, BrowserTokenResult, ChatsvcaggTokenResult, Ic3TokenResult, ChromiumLike, ContextLike, ElevatedFailureReason, ElevatedTokenResult, PageLike, PlaywrightLoader, RequestLike, ResponseLike, };

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

@@ -5,6 +5,7 @@ type GraphError = {
     status: number;
     message: string;
     code?: string;
+    retryAfterSeconds?: number;
 } | {
     type: 'auth_failed';
     message: string;
@@ -66,6 +67,7 @@ type GraphClient = {
      */
     teamsChatIc3: (path: string) => Promise<Result<unknown, GraphError>>;
     post: (path: string, body: unknown) => Promise<Result<unknown, GraphError>>;
+    patch: (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"
@@ -107,7 +109,7 @@ type TokenInfo = {
     /**
      * 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
+     * when the JWT did not carry an `exp` claim. Audit Jane-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.
      */

package/dist/infra/legacy-doc-extractor.d.ts

@@ -0,0 +1,14 @@
+import type { Result } from '../domain/result.js';
+import type { GraphError } from './graph-client.js';
+/**
+ * Extract the text of a legacy Word .doc — the pre-2007 OLE binary "Compound
+ * File" format that mammoth (which only reads the OOXML .docx zip) cannot parse —
+ * via word-extractor (pure-JS, walks the WordDocument OLE stream; no native deps).
+ * Body text only: legacy .doc carries no structure this CLI surfaces (headings,
+ * tables, and styling are lost), so callers return it as text/plain.
+ *
+ * try/catch is permitted here per the infra-boundary rule: word-extractor throws
+ * on a non-.doc / corrupt OLE container, and we translate that into a Result.
+ */
+declare const extractDocText: (bytes: Uint8Array) => Promise<Result<string, GraphError>>;
+export { extractDocText };

package/dist/infra/msg-reader-adapter.d.ts

@@ -0,0 +1,83 @@
+import type { Result } from '../domain/result.js';
+import type { GraphError } from './graph-client.js';
+/**
+ * Parse an Outlook `.msg` file — the OLE Compound File (CFBF) container Outlook
+ * writes when you drag an email to disk, same binary family as legacy .doc/.xls —
+ * into a clean {@link ParsedMsg} via @kenjiuno/msgreader (pure-JS, no native deps,
+ * lazy-imported like word-extractor / unpdf so it stays out of the cold-start path).
+ *
+ * The adapter is the anti-corruption layer: msgreader returns a wide `FieldsData`
+ * (X500 sender addresses, RTF body, hundreds of MAPI props); {@link mapRawMsg}
+ * narrows it to the half-dozen fields the markdown renderer needs and resolves the
+ * sender SMTP / delivery-time fallbacks. `mapRawMsg` is pure and exported so every
+ * fallback branch is unit-tested with plain objects — the binary fixture only
+ * exercises one field combination.
+ *
+ * try/catch is permitted here per the infra-boundary rule: msgreader throws on a
+ * non-OLE / corrupt container, and a single unreadable attachment must not sink the
+ * whole parse, so attachment reads are individually guarded.
+ */
+type MsgRecipientKind = 'to' | 'cc' | 'bcc' | 'unknown';
+type MsgRecipient = {
+    readonly kind: MsgRecipientKind;
+    readonly name?: string;
+    readonly email?: string;
+};
+type MsgAttachment = {
+    readonly fileName?: string;
+    readonly content?: Uint8Array;
+};
+type ParsedMsg = {
+    readonly subject?: string;
+    readonly senderName?: string;
+    readonly senderEmail?: string;
+    readonly date?: string;
+    readonly body?: string;
+    readonly bodyHtml?: string;
+    readonly recipients: readonly MsgRecipient[];
+    readonly attachments: readonly MsgAttachment[];
+};
+type RawRecipient = {
+    readonly recipType?: string;
+    readonly name?: string;
+    readonly smtpAddress?: string;
+    readonly email?: string;
+};
+type RawAttachment = {
+    readonly fileName?: string;
+};
+type RawMsg = {
+    readonly subject?: string;
+    readonly senderName?: string;
+    readonly senderSmtpAddress?: string;
+    readonly senderEmail?: string;
+    readonly messageDeliveryTime?: string;
+    readonly clientSubmitTime?: string;
+    readonly body?: string;
+    readonly bodyHtml?: string;
+    readonly recipients?: readonly RawRecipient[];
+    readonly attachments?: readonly RawAttachment[];
+};
+declare const mapRawMsg: (raw: RawMsg, attachmentContents: readonly (Uint8Array | undefined)[]) => ParsedMsg;
+type AttachmentReader = {
+    readonly getAttachment: (index: number) => {
+        readonly content?: unknown;
+    };
+};
+type MsgReaderInstance = AttachmentReader & {
+    readonly getFileData: () => unknown;
+};
+type MsgReaderCtor = new (input: ArrayBuffer | DataView) => MsgReaderInstance;
+declare const readAttachmentContent: (reader: AttachmentReader, index: number) => Uint8Array | undefined;
+/**
+ * Resolve the MsgReader class from the dynamic import's `default`, whichever
+ * interop shape it arrives in. msgreader is CJS with `exports.default = class`
+ * (+ `__esModule`): Bun's RUNTIME import hands us the class directly, but Bun's
+ * BUNDLER (node-mode `__toESM`) sets `default` to the whole exports object —
+ * so in `dist/cli.js` the class sits one level deeper at `default.default`
+ * ("Object is not a constructor" at runtime, invisible to source-run tests).
+ */
+declare const resolveMsgReaderCtor: (defaultExport: unknown) => MsgReaderCtor;
+declare const extractMsg: (bytes: Uint8Array) => Promise<Result<ParsedMsg, GraphError>>;
+export { extractMsg, mapRawMsg, readAttachmentContent, resolveMsgReaderCtor };
+export type { MsgAttachment, MsgRecipient, MsgRecipientKind, ParsedMsg };

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

@@ -3,7 +3,7 @@ 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 HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
 export type TimeoutTier = 'json' | 'binary';
 export declare const timeoutLabelFor: (tier: TimeoutTier) => string;
 export declare const timeoutMsFor: (tier: TimeoutTier) => number;

package/dist/infra/ooxml-media-extractor.d.ts

@@ -0,0 +1,27 @@
+import type { Result } from '../domain/result.js';
+import type { GraphError } from './graph-client.js';
+/**
+ * Pulls the image parts out of an OOXML package (.docx / .xlsx /
+ * .pptx and their macro-enabled / template variants). Images live as binary
+ * parts under `word/media/`, `xl/media/`, or `ppt/media/` — including
+ * original full-resolution / un-cropped originals and images on hidden
+ * slides that the rendered view never shows.
+ *
+ * Separate from `ooxml-zip-adapter` on purpose: that adapter pre-decodes
+ * every entry as a UTF-8 string (correct for XML, corrupting for binary),
+ * whereas media must come back as raw bytes. try/catch is permitted here
+ * (src/infra/**, atelier rule 17): a malformed-zip throw becomes a Result.err.
+ *
+ * Raster formats (png/jpg/gif/bmp/tiff/webp) a vision model can read directly,
+ * plus svg — the one vector format a model can use, because its XML source
+ * carries the diagram's own text labels (and modern Office embeds it as the
+ * high-fidelity original beside a png fallback). Legacy vector (emf/wmf) and
+ * audio/video are still excluded — neither a model can use.
+ */
+type MediaPart = {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+};
+declare const extractOoxmlMedia: (bytes: Uint8Array) => Promise<Result<ReadonlyArray<MediaPart>, GraphError>>;
+export { extractOoxmlMedia };
+export type { MediaPart };

package/dist/infra/ooxml-zip-adapter.d.ts

@@ -0,0 +1,28 @@
+import type { Result } from '../domain/result.js';
+import type { GraphError } from './graph-client.js';
+/**
+ * Thin wrapper around JSZip for opening already-fetched OOXML bytes
+ * (.docx / .xlsx / .pptx — all ZIP packages with a shared docProps/* core).
+ * Pure CPU on bytes already in memory — no IO — so this matches the
+ * mammoth-adapter pattern: a Result-returning factory, no port, no fake.
+ * Tests work end-to-end against real fixtures built with the `docx` /
+ * `xlsx` packages (or hand-rolled JSZip) via test-helpers/office-fixtures.ts.
+ *
+ * try/catch is permitted under src/infra/** (atelier hard rule 17): any
+ * malformed-zip throw from JSZip translates into a Result.err with a
+ * GraphError shape so callers stay on the Result rail.
+ *
+ * The returned reader is synchronous on purpose: callers in the use-case
+ * layer are pure XML walkers that don't model async/await internally.
+ * Every text entry is pre-decoded once at open time, then served from
+ * an in-memory map. `list()` exposes the entry paths so callers can
+ * enumerate numbered parts (`xl/comments1.xml`, `ppt/slides/slide*.xml`,
+ * every `*.rels`) that can't be hardcoded.
+ */
+type OoxmlZip = {
+    readonly read: (path: string) => string | undefined;
+    readonly list: () => ReadonlyArray<string>;
+};
+declare const openOoxmlZip: (bytes: Uint8Array) => Promise<Result<OoxmlZip, GraphError>>;
+export { openOoxmlZip };
+export type { OoxmlZip };

package/dist/infra/pdf-image-extractor.d.ts

@@ -0,0 +1,18 @@
+import type { Result } from '../domain/result.js';
+import type { GraphError } from './graph-client.js';
+import type { MediaPart } from './ooxml-media-extractor.js';
+/**
+ * Extract embedded raster images from a PDF via unpdf (a pure-JS pdfjs build — no
+ * native deps, runs under Bun). unpdf walks each page's painted image XObjects and
+ * returns *decoded* pixels, which we PNG-encode.
+ *
+ * Scope note: this is page-oriented — it sees images AS PAINTED on each page. It does
+ * NOT reach OCG/layer-hidden images, unpainted/orphan XObjects, or the full uncropped
+ * original behind a clipped image; capturing those needs an object-graph walk (a much
+ * heavier dependency). All PAGES are always walked (PDF has no "hidden page" concept).
+ *
+ * `try/catch` is permitted here per the infra-boundary rule: pdfjs throws on malformed
+ * input and we translate that into a Result rather than letting it escape.
+ */
+declare const extractPdfImages: (bytes: Uint8Array) => Promise<Result<ReadonlyArray<MediaPart>, GraphError>>;
+export { extractPdfImages };

package/dist/infra/pdf-text-extractor.d.ts

@@ -0,0 +1,41 @@
+import type { Result } from '../domain/result.js';
+import type { GraphError } from './graph-client.js';
+/**
+ * Extract a PDF's text layer via unpdf (a pure-JS pdfjs build — no native deps,
+ * runs under Bun). Returns the reading-order text of every page merged into one
+ * string. A born-digital PDF (exported from Word/LaTeX/Chrome/…) yields its text;
+ * a scanned / image-only PDF has no text layer, so the string comes back empty —
+ * callers treat that as "needs OCR / a vision model", never as success-with-text.
+ *
+ * Scope note: this is the embedded text layer, NOT OCR. It also does not preserve
+ * layout structure (headings, tables, columns flatten into reading order).
+ *
+ * `try/catch` is permitted here per the infra-boundary rule: pdfjs throws on
+ * malformed input and we translate that into a Result rather than letting it escape.
+ *
+ * `verbosity: 0` (pdfjs `VerbosityLevel.ERRORS`) silences pdfjs's TrueType
+ * font-hinting log spam — `Warning: TT: undefined function: N`, `Required "glyf"
+ * table is not found`, `Indexing all PDF objects` — which it emits via its own
+ * `console.warn` while parsing a PDF's embedded fonts. Font hinting is sub-pixel
+ * glyph rendering, completely irrelevant to text extraction (the text still comes
+ * out fine); the default level (WARNINGS) just floods the host app's logs once per
+ * quirky font. We lower it at the boundary because the noise originates inside
+ * pdfjs — the `no-console` rule keeps us from emitting or intercepting it ourselves.
+ */
+/**
+ * Map a pdfjs throw to an actionable message. The special case is an encrypted
+ * PDF: pdfjs raises `PasswordException` ("No password given") — QA run-1 found a
+ * real tenant file surfacing that raw string with zero guidance. Password
+ * handling is genuinely unsupported (and Graph's `format=pdf` cannot unlock
+ * encrypted sources either), so say that honestly instead of leaking pdfjs
+ * internals. Pure and exported: the branch is unit-tested with shaped errors —
+ * no encrypted-PDF fixture exists in the toolchain.
+ */
+declare const pdfErrorMessage: (e: unknown) => string;
+type PdfText = {
+    readonly text: string;
+    readonly pageCount: number;
+};
+declare const extractPdfText: (bytes: Uint8Array) => Promise<Result<PdfText, GraphError>>;
+export { extractPdfText, pdfErrorMessage };
+export type { PdfText };

package/dist/infra/png-encode.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal, dependency-free PNG encoder for raw 8-bit pixel buffers. unpdf hands
+ * back *decoded* pixels (1=grayscale, 3=RGB, 4=RGBA channels), so to write usable
+ * image files without a native dep (sharp/canvas) we wrap them in a PNG ourselves:
+ * signature + IHDR + a single zlib-compressed IDAT (filter-0 scanlines) + IEND.
+ */
+type RawImage = {
+    readonly width: number;
+    readonly height: number;
+    readonly channels: number;
+    readonly data: Uint8Array;
+};
+declare const encodePng: (image: RawImage) => Uint8Array;
+export { encodePng };
+export type { RawImage };

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

@@ -4,6 +4,6 @@ type SheetCsv = {
     readonly name: string;
     readonly csv: string;
 };
-declare const readSheetsAsCsv: (bytes: Uint8Array) => Result<ReadonlyArray<SheetCsv>, GraphError>;
+declare const readSheetsAsCsv: (bytes: Uint8Array) => Promise<Result<ReadonlyArray<SheetCsv>, GraphError>>;
 export { readSheetsAsCsv };
 export type { SheetCsv };

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

@@ -0,0 +1,35 @@
+import type { AccessToken } from '../domain/access-token.js';
+import type { Result } from '../domain/result.js';
+import type { Logger } from '../use-cases/ports/logger.js';
+type SystemBrowserAuthDeps = {
+    readonly logger: Logger;
+    readonly timeoutMs?: number;
+    readonly extensionTimeoutMs?: number;
+};
+type SystemBrowserTokenResult = {
+    readonly accessToken: AccessToken;
+    readonly refreshToken: string | null;
+    readonly elevatedAccessToken?: AccessToken | null;
+    readonly chatsvcaggAccessToken?: AccessToken | null;
+    readonly ic3AccessToken?: AccessToken | null;
+    readonly chatsvcaggRegion?: string;
+};
+type SystemBrowserAuthError = {
+    type: 'server_bind_failed';
+    message: string;
+} | {
+    type: 'browser_open_failed';
+    message: string;
+} | {
+    type: 'extension_timeout';
+    message: string;
+} | {
+    type: 'invalid_token';
+    message: string;
+} | {
+    type: 'cancelled';
+    message: string;
+};
+declare const authenticateViaSystemBrowser: (deps: SystemBrowserAuthDeps) => Promise<Result<SystemBrowserTokenResult, SystemBrowserAuthError>>;
+export { authenticateViaSystemBrowser };
+export type { SystemBrowserAuthDeps, SystemBrowserAuthError, SystemBrowserTokenResult };

package/dist/infra/system-browser-loader.d.ts

@@ -0,0 +1,3 @@
+import type { Logger } from '../use-cases/ports/logger.js';
+import type { SystemBrowserAuthFn } from './auth.js';
+export declare const defaultSystemBrowserAuth: (logger: Logger, skipSystemBrowser: boolean) => SystemBrowserAuthFn;

package/dist/infra/token-callback-server.d.ts

@@ -0,0 +1,31 @@
+import type { Result } from '../domain/result.js';
+import type { Logger } from '../use-cases/ports/logger.js';
+type TokenCallbackPayload = {
+    readonly access_token: string;
+    readonly refresh_token?: string;
+    readonly elevated_access_token?: string;
+    readonly chatsvcagg_access_token?: string;
+    readonly ic3_access_token?: string;
+    readonly chatsvcagg_region?: string;
+};
+type TokenCallbackServer = {
+    readonly port: number;
+    readonly start: () => Promise<Result<TokenCallbackPayload, TokenCallbackError>>;
+    readonly stop: () => Promise<void>;
+};
+type TokenCallbackError = {
+    type: 'bind_failed';
+    message: string;
+} | {
+    type: 'timeout';
+    message: string;
+} | {
+    type: 'invalid_payload';
+    message: string;
+} | {
+    type: 'server_closed';
+    message: string;
+};
+declare const createTokenCallbackServer: (logger: Logger, timeoutMs?: number) => TokenCallbackServer;
+export { createTokenCallbackServer };
+export type { TokenCallbackError, TokenCallbackPayload, TokenCallbackServer };

package/dist/infra/zip-reader.d.ts

@@ -0,0 +1,32 @@
+import type { Result } from '../domain/result.js';
+import type { GraphError } from './graph-client.js';
+/**
+ * Reads every file entry out of an arbitrary `.zip` archive as raw bytes,
+ * sorted by path, directories excluded. Generic counterpart to
+ * `ooxml-media-extractor` (which matches only media paths) and
+ * `ooxml-zip-adapter` (which decodes entries as UTF-8 strings) — used by the
+ * zip-conversion commands to fan each contained file out to the right
+ * converter. try/catch is permitted here (src/infra/**, atelier rule 17): a
+ * malformed-zip throw becomes a Result.err.
+ */
+type ZipEntry = {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+};
+/**
+ * Decode a legacy zip entry name — the raw filename bytes of an entry whose
+ * UTF-8 flag (general-purpose bit 11) is NOT set and which carries no Info-ZIP
+ * Unicode-path extra field. JSZip's default decoder assumes UTF-8 and mojibakes
+ * these (the `unzip -O GBK` case): Chinese vendor archives written by WinRAR /
+ * Windows Explorer store names in GBK. Try strict UTF-8 first (some archivers
+ * emit UTF-8 bytes without setting the flag), then fall back to GB18030 — a GBK
+ * superset whose 0x00–0x7F bytes are plain ASCII, so legacy ASCII/CP437 names
+ * survive unchanged while CJK byte sequences decode correctly.
+ *
+ * Only reached for non-UTF-8-flagged names (JSZip handles UTF-8 names itself),
+ * so a UTF-8 archive's path-handling is unchanged.
+ */
+declare const decodeZipFileName: (bytes: Uint8Array) => string;
+declare const openZipEntries: (bytes: Uint8Array) => Promise<Result<ReadonlyArray<ZipEntry>, GraphError>>;
+export { decodeZipFileName, openZipEntries };
+export type { ZipEntry };

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

@@ -1,7 +1,7 @@
 /**
  * Translate Graph / substrate / CLI / validation errors into actionable hints.
  *
- * Audit Hervé-session §2: bare `error: ErrorInvalidIdMalformed: Id is
+ * Audit Jane-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
@@ -12,7 +12,7 @@
  * `--output text` (as `hint:` / `source:` lines under the existing `error:`
  * line).
  *
- * Audit Hervé-session §2 follow-up: the four error-envelope variants are
+ * Audit Jane-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}`.

package/dist/presenter/output.d.ts

@@ -2,6 +2,6 @@ import type { Logger } from '../use-cases/ports/logger.js';
 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;
+declare const renderError: (message: string, format: OutputFormat, errorCode?: string, explicitSource?: ErrorSource, retryAfterSeconds?: number) => void;
 export { render, renderError };
 export type { OutputFormat };

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

@@ -7,7 +7,7 @@ import { type ODataKey } from './odata-query.js';
  * 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`
+ * `--select` always wins. Audit Jane-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.
  */

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

@@ -80,6 +80,14 @@ type PaginationStrategy =
 type CommandMeta = {
     readonly summary: string;
     readonly category: CommandCategory;
+    /**
+     * Deprecated former command names kept working as commander-level aliases for
+     * back-compat after a rename (e.g. `download-onedrive-file-content` →
+     * `download-drive-item-content`). The canonical registry key is what `--help`
+     * and the manifest list first; each alias here is also accepted on the CLI and
+     * surfaced in the manifest so an LLM that learned the old name still resolves.
+     */
+    readonly commandAliases?: ReadonlyArray<string>;
     readonly graphMethod: CommandHttpMethod;
     readonly graphPathTemplate: string;
     readonly graphDocsUrl: string;
@@ -107,6 +115,14 @@ type CommandMeta = {
      * commands will time out.
      */
     readonly needsElevatedToken?: true;
+    /**
+     * `true` if the command needs a Teams substrate token (chatsvcagg or ic3,
+     * captured at login from `teams.microsoft.com`) — the Teams chat-content
+     * commands. Like `needsElevatedToken`, an LLM should check this before
+     * invoking and warm up an interactive `login`; a headless or stale session
+     * times out on these (the non-interactive silent-SSO limitation, QA-011).
+     */
+    readonly needsSubstrateToken?: true;
     /**
      * `true` if the command returns inlined bytes (`{contentType, size, base64}`
      * or `{contentType, size, text}`) and is therefore a valid target for the
@@ -115,6 +131,24 @@ type CommandMeta = {
      * as a string literal. Audit round-8 Wave E2.
      */
     readonly producesBytes?: true;
+    /**
+     * `true` if the command returns a `media` array (`{ count, media: [{ path,
+     * contentType, sizeBytes, base64 }] }`) and is therefore a valid target for
+     * the global `--output-dir` flag, which writes each image to a directory.
+     * Parallel to `producesBytes` (single-file `--output-path`).
+     */
+    readonly producesMedia?: true;
+    /**
+     * `true` if the command performs a write (mutation) against Microsoft Graph
+     * rather than a read/search. Today only the two mail-draft commands
+     * (`create-mail-draft` = POST, `update-mail-draft` = PATCH) — both produce an
+     * UNSENT draft and cannot send. The CLI composition derives its read-only
+     * top-level `--help` narrative from this flag (mutating commands vs search
+     * POSTs) instead of hardcoding command names, and the manifest/`help-json`
+     * surface it so an LLM can tell at a glance which commands change state.
+     * Audit 2026-06-15 (F-03).
+     */
+    readonly mutates?: true;
     /**
      * Stability tier of the command. Omitted from manifest entries when the
      * command is `'stable'` (the implicit default), surfaced only on
@@ -123,7 +157,7 @@ type CommandMeta = {
      * substrate (chatsvcagg / IC3) that is not in the public Graph API and can
      * break on a Teams web-client update — the docstring "Best-effort, may break
      * on Microsoft client updates" warnings now have a structured pair.
-     * Audit Hervé-session §6.
+     * Audit Jane-session §6.
      */
     readonly stability?: 'experimental';
 };
@@ -131,5 +165,12 @@ type Command = {
     readonly schema: CommandSchema;
     readonly execute: CommandExecute;
     readonly meta: CommandMeta;
+    /**
+     * Present on the rare command whose input is the LOCAL filesystem instead of
+     * Graph (`convert-local-file`). The CLI routes execution here, passing its
+     * composition-selected FileSystem; `execute` stays as the registry-typed
+     * fallback that redirects library consumers to this variant.
+     */
+    readonly executeLocal?: (fs: import('../ports/filesystem.js').FileSystem, params: Record<string, string>) => Promise<Result<unknown, import('../../infra/graph-client.js').GraphError>>;
 };
 export type { ArgumentHint, Command, CommandCategory, CommandExecute, CommandHttpMethod, CommandMeta, CommandOptionAlias, CommandOptionMeta, CommandPositionalArgumentMeta, CommandSchema, PaginationStrategy, };

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

@@ -0,0 +1,15 @@
+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<{
+    eventId: z.ZodString;
+    attachmentId: z.ZodString;
+    includeMetadata: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+}, 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-calendar-event-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<{
+    eventId: 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-drive-item-zip.d.ts

@@ -0,0 +1,26 @@
+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';
+/**
+ * Unzips a `.zip` from a OneDrive / SharePoint item and runs each contained
+ * file through the same local conversion pipelines the `*-as-markdown` commands
+ * use — so an agent reading "the project handover archive" doesn't have to shell
+ * out to `unzip` and convert each file separately. Office files (docx/xlsx/pptx/
+ * odt/ods/odp + variants) become markdown; legacy OLE .xls / .doc are extracted
+ * too (.ppt is noted, no pure-JS path); plain-text entries are decoded inline;
+ * PDFs have their text layer extracted; everything else (images, binaries, nested
+ * archives — plus scanned/image-only PDFs and legacy .ppt) is listed with a note
+ * rather than failing the whole archive.
+ */
+declare const schema: z.ZodObject<{
+    driveId: z.ZodString;
+    itemId: z.ZodString;
+    includeMetadata: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+}, z.core.$strip>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, meta, schema };