ask-marcel-office-cli 1.0.0 → 1.4.0

package/dist/infra/auth.d.ts

@@ -31,6 +31,30 @@ type AuthManager = {
      * 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
@@ -39,6 +63,12 @@ type AuthManager = {
      * 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, browserProfileDir: string, logger: Logger, fs: FileSystem) => AuthManager;
 declare const createAuthManager: (deps: {

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

@@ -26,19 +26,62 @@ type ElevatedTokenResult = {
     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.
+ * 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>;
@@ -62,6 +105,28 @@ type BrowserAuth = {
      * `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,
@@ -160,4 +225,4 @@ declare const createBrowserAuth: (deps: {
     fs?: FileSystem;
 }) => BrowserAuth;
 export { createBrowserAuth, createBrowserAuthFromApi, createPlaywrightApi };
-export type { BothTokensResult, BrowserAuth, BrowserAuthApi, BrowserAuthConfig, BrowserTokenResult, ChromiumLike, ContextLike, ElevatedFailureReason, ElevatedTokenResult, PageLike, PlaywrightLoader, RequestLike, 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

@@ -35,6 +35,36 @@ type GraphClient = {
      * 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>>;
     /**
@@ -74,6 +104,14 @@ 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;

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/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.d.ts

@@ -1,6 +1,7 @@
 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) => 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,10 +1,23 @@
 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">;
 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">;
+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
@@ -13,14 +26,23 @@ declare const buildElevatedListCommand: <Shape extends z.ZodRawShape>(pathFn: (p
  * 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">;
+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>) => Pick<Command, "schema" | "execute">;
+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`,
@@ -28,7 +50,7 @@ declare const buildFilterSelectListCommand: <Shape extends z.ZodRawShape>(pathFn
  * `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">;
+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
@@ -37,12 +59,12 @@ declare const buildNoSkipListCommand: <Shape extends z.ZodRawShape>(pathFn: (par
  * (`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">;
+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>) => Pick<Command, "schema" | "execute">;
-export { buildCommand, buildElevatedCommand, buildElevatedListCommand, buildElevatedPickODataListCommand, buildFilterSelectListCommand, buildListCommand, buildNoSkipListCommand, buildPickODataListCommand, buildSelectableCommand, };
+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, };

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

@@ -3,7 +3,7 @@ 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' | 'lifecycle';
+type CommandCategory = 'drive' | 'excel' | 'sharepoint' | 'tasks' | 'mail' | 'notes' | 'user' | 'calendar' | 'chats' | 'teams' | 'meta' | 'lifecycle';
 type CommandHttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
 type CommandOptionAlias = {
     readonly name: string;
@@ -115,6 +115,17 @@ type CommandMeta = {
      * as a string literal. Audit round-8 Wave E2.
      */
     readonly producesBytes?: true;
+    /**
+     * Stability tier of the command. Omitted from manifest entries when the
+     * command is `'stable'` (the implicit default), surfaced only on
+     * `'experimental'` commands so an LLM can prefer stable siblings when they
+     * exist. `'experimental'` today means the command rides a Microsoft-internal
+     * 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.
+     */
+    readonly stability?: 'experimental';
 };
 type Command = {
     readonly schema: CommandSchema;

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

@@ -4,6 +4,10 @@ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
 import type { CommandMeta } from './command-types.js';
 declare const schema: z.ZodObject<{
     messageId: z.ZodString;
+    inlineImages: 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;

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

@@ -1,4 +1,4 @@
-import type { CommandCategory, CommandMeta } from './command-types.js';
+import type { CommandCategory, CommandMeta, PaginationStrategy } from './command-types.js';
 export type CommandManifestEntry = {
     readonly name: string;
     readonly summary: string;
@@ -16,8 +16,10 @@ export type CommandManifestEntry = {
     readonly scopesRequired?: CommandMeta['scopesRequired'];
     readonly needsElevatedToken?: CommandMeta['needsElevatedToken'];
     readonly producesBytes?: CommandMeta['producesBytes'];
+    readonly stability?: CommandMeta['stability'];
 };
-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 declare const paginationHintFor: (strategy: PaginationStrategy | undefined) => string;
+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. 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/docs.d.ts

@@ -1,10 +1,53 @@
 import type { Result } from '../../domain/result.js';
-import type { Command } from './command-types.js';
+import type { CommandCategory, Command, CommandMeta } from './command-types.js';
 import type { CommandManifest } from './docs-render.js';
 export type DocsError = {
     type: 'unknown_command';
     readonly name: string;
     readonly available: ReadonlyArray<string>;
 };
+/**
+ * Terse manifest entry — only the fields an LLM needs to *discover* a command
+ * (i.e. "does this CLI do X?"). Drops `options`, `example`, `graphPathTemplate`,
+ * `graphDocsUrl`, `responseShape`, `bodyTemplate`, `paginationStrategy`,
+ * `scopesRequired` — everything the LLM only needs once it's already decided
+ * to invoke. `stability` is kept (it's a discovery-time concern: LLMs prefer
+ * stable siblings when they exist, so they need to see the tag at discovery
+ * time, not after a second full-manifest fetch). Audit Hervé-session §B/§6.
+ */
+export type TerseManifestEntry = {
+    readonly name: string;
+    readonly summary: string;
+    readonly category: CommandCategory;
+    readonly stability?: CommandMeta['stability'];
+};
+export type TerseManifest = {
+    readonly package: string;
+    readonly version: string;
+    readonly generatedAt: string;
+    readonly commands: ReadonlyArray<TerseManifestEntry>;
+};
+export type ManifestFilterError = {
+    readonly type: 'unknown_category';
+    readonly category: string;
+    readonly available: ReadonlyArray<string>;
+};
 export declare const buildManifest: (registry: Readonly<Record<string, Command>>, packageName: string, version: string, now?: () => Date) => CommandManifest;
+/**
+ * Terse manifest — `{ name, summary, category }` per command. Roughly 95%
+ * smaller than the full manifest (no options/example/Graph endpoint per entry).
+ * Use `help-json --terse` to surface this to an LLM as the discovery view.
+ */
+export declare const buildTerseManifest: (registry: Readonly<Record<string, Command>>, packageName: string, version: string, now?: () => Date) => TerseManifest;
+/**
+ * Filter a `CommandManifest` (or terse variant) down to a single category.
+ * Returns `err({ type: 'unknown_category', ... })` if the requested category
+ * isn't a known one — the CLI surfaces this through the standard error
+ * envelope rather than silently returning an empty list.
+ */
+export declare const filterManifestByCategory: <M extends {
+    readonly commands: ReadonlyArray<{
+        readonly category: CommandCategory;
+    }>;
+}>(manifest: M, category: string) => Result<M, ManifestFilterError>;
 export declare const renderSingleCommand: (registry: Readonly<Record<string, Command>>, name: string) => Result<string, DocsError>;

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

@@ -6,6 +6,11 @@ declare const schema: z.ZodObject<{
     driveId: z.ZodString;
     itemId: z.ZodString;
     versionId: z.ZodString;
+    format: z.ZodOptional<z.ZodEnum<{
+        markdown: "markdown";
+        pdf: "pdf";
+        original: "original";
+    }>>;
 }, z.core.$strip>;
 declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
 declare const meta: CommandMeta;

package/dist/use-cases/commands/fetch-raw-bytes.d.ts

@@ -44,7 +44,7 @@ export declare const inlineBinary: (graph: GraphClient, contentPath: string, opt
  * reference-attachment edge cases) Graph silently falls back to returning
  * the raw source bytes — same envelope shape, but contentType is the
  * source MIME (or `application/octet-stream`). The audit (round-5 #2)
- * caught this happening on `download-drive-item-version-as-pdf` for v79
+ * caught this happening on `download-drive-item-version --format pdf` for v79
  * of a pptx: the response said `contentType: "application/octet-stream"`
  * with the exact source byte size, and an LLM that saved it as `.pdf`
  * would have had a corrupt file.

package/dist/use-cases/commands/find-chats-with-user.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    name: z.ZodString;
+    maxPages: z.ZodOptional<z.ZodString>;
+    pageSize: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const execute: Command['execute'];
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/get-chat.d.ts

@@ -1,8 +1,4 @@
-import { z } from 'zod';
 import type { CommandMeta } from './command-types.js';
-declare const schema: z.ZodObject<{
-    chatId: z.ZodString;
-}, z.core.$strip>;
-declare const execute: import("./command-types.js").CommandExecute;
+declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
 declare const meta: CommandMeta;
 export { execute, meta, schema };

package/dist/use-cases/commands/get-excel-used-range.d.ts

@@ -1,10 +1,15 @@
 import { z } from 'zod';
-import type { CommandMeta } from './command-types.js';
+import type { Command, CommandMeta } from './command-types.js';
 declare const schema: z.ZodObject<{
     driveId: z.ZodString;
     itemId: z.ZodString;
     worksheetId: z.ZodString;
+    full: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    maxCells: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-declare const execute: (graph: import("../../index.js").GraphClient, params: Record<string, string>) => Promise<import("../../index.js").Result<unknown, import("../../index.js").GraphError>>;
+declare const execute: Command['execute'];
 declare const meta: CommandMeta;
 export { execute, meta, schema };

package/dist/use-cases/commands/get-teams-chat-message.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    chatId: z.ZodString;
+    messageId: z.ZodString;
+}, z.core.$strip>;
+declare const execute: Command['execute'];
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/iso-datetime-schema.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+/**
+ * Reusable Zod field for an ISO-8601 UTC datetime parameter that ALSO accepts
+ * the relative-date vocabulary defined in `src/domain/iso-datetime.ts`
+ * (`7d`, `1w`, `today`, `monday`, `start-of-month`, etc.). Calendar commands
+ * compose this into their schemas in place of `z.string().min(1)`; the
+ * URL-builder sees the already-resolved canonical ISO form.
+ *
+ * Audit Hervé-session §C: removes the manual ISO arithmetic an LLM had to do
+ * to ask "what changed this week" against `list-calendar-view`. Type
+ * inference is left to Zod so the calendar commands' shape signatures stay
+ * compatible with `buildListCommand`'s `ZodRawShape` constraint.
+ */
+export declare const isoDateTimeField: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../domain/iso-datetime.js").IsoDateTime, string>>;
+/**
+ * Standard `--start-date-time` / `--end-date-time` description used by every
+ * calendar-view command. Mentions both the strict ISO form Graph expects and
+ * the relative vocabulary the CLI also accepts, so the LLM sees both options
+ * in `--help`.
+ */
+export declare const RELATIVE_DATE_DESCRIPTION = "ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC).";

package/dist/use-cases/commands/link-shape.d.ts

@@ -0,0 +1,13 @@
+type SiblingResolver = 'mail' | 'calendar' | 'teams' | 'drive-share';
+/**
+ * Classify a Zod-validated URL string by which sibling resolver it
+ * belongs to. Returns `null` when the URL matches none of the known
+ * resolver families (caller falls through to its own "unknown URL"
+ * rejection message).
+ *
+ * Precondition: `raw` has been validated through `z.url()`. Calling
+ * with an unvalidated string is a programmer error — `new URL(raw)`
+ * will throw and the atelier rule forbids try/catch outside infra.
+ */
+export declare const detectSiblingResolver: (raw: string) => SiblingResolver | null;
+export type { SiblingResolver };

package/dist/use-cases/commands/list-calendar-view-delta.d.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 import type { Command, CommandMeta } from './command-types.js';
 declare const schema: z.ZodObject<{
-    startDateTime: z.ZodString;
-    endDateTime: z.ZodString;
+    startDateTime: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../domain/iso-datetime.js").IsoDateTime, string>>;
+    endDateTime: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../domain/iso-datetime.js").IsoDateTime, string>>;
     top: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const execute: Command['execute'];

package/dist/use-cases/commands/list-teams-chat-history.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    chatId: z.ZodString;
+    syncState: z.ZodOptional<z.ZodURL>;
+    pageSize: z.ZodOptional<z.ZodString>;
+    maxPages: z.ZodOptional<z.ZodString>;
+    full: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    maxContentChars: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const execute: Command['execute'];
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/list-teams-chat-messages.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    chatId: z.ZodString;
+}, z.core.$strip>;
+declare const execute: Command['execute'];
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/list-teams-chats-with-messages.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    pageSize: z.ZodOptional<z.ZodString>;
+    continuationToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const execute: Command['execute'];
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/resolve-calendar-link.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    url: z.ZodURL;
+}, z.core.$strip>;
+declare const execute: Command['execute'];
+declare const meta: CommandMeta;
+export { execute, meta, schema };