ask-marcel-office-cli 2.1.0 → 2.2.0

package/dist/use-cases/commands/get-mail-signature.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    messageId: 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-user.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    userId: z.ZodString;
+    select: z.ZodOptional<z.ZodString>;
+    expand: 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/inline-image-embedder.d.ts

@@ -16,5 +16,6 @@ type InlineAttachment = {
     readonly contentBytes: string;
 };
 declare const embedInlineImages: (html: string, attachments: ReadonlyArray<InlineAttachment>) => string;
-export { embedInlineImages };
+declare const replaceUnresolvedCidImages: (html: string, labelByContentId: ReadonlyMap<string, string>) => string;
+export { embedInlineImages, replaceUnresolvedCidImages };
 export type { InlineAttachment };

package/dist/use-cases/commands/login-status.d.ts

@@ -1,31 +1,13 @@
-type RefreshRoute = 'automatic' | 'interactive';
-type TokenTier = {
-    readonly available: boolean;
-    readonly expiresInSeconds: number | undefined;
-};
-type TokenView = {
-    available: boolean;
-    expiresInSeconds?: number;
-    refresh: RefreshRoute;
-    reason?: string;
-};
-type LoginStatus = {
+type LoginSummary = {
     status: 'authenticated';
-    tokens: {
-        basic: TokenView;
-        elevated: TokenView;
-        chatsvcagg: TokenView;
-        ic3: TokenView;
-    };
+    available: ReadonlyArray<string>;
     hint: string;
 };
-type LoginStatusInput = {
-    readonly basicExpiresInSeconds: number | undefined;
-    readonly elevated: TokenTier;
-    readonly chatsvcagg: TokenTier;
-    readonly ic3: TokenTier;
-    readonly elevatedFailureReason?: string;
+type LoginSummaryInput = {
+    readonly elevatedAvailable: boolean;
+    readonly chatsvcaggAvailable: boolean;
+    readonly ic3Available: boolean;
 };
-declare const buildLoginStatus: (input: LoginStatusInput) => LoginStatus;
-export { buildLoginStatus };
-export type { LoginStatus, LoginStatusInput };
+declare const buildLoginSummary: (input: LoginSummaryInput) => LoginSummary;
+export { buildLoginSummary };
+export type { LoginSummary, LoginSummaryInput };

package/dist/use-cases/commands/login.d.ts

@@ -2,6 +2,27 @@ import { z } from 'zod';
 import type { Result } from '../../domain/result.js';
 import type { AuthManager } from '../../infra/auth.js';
 declare const schema: z.ZodObject<{}, z.core.$strict>;
+/**
+ * Sign in, and guarantee the browser-only tier is actually there afterwards.
+ *
+ * Every other token tier can be renewed headlessly from the shared refresh
+ * token. The elevated (M365ChatClient) token cannot — it carries no refresh
+ * token of its own and exists only via the browser dance. So a plain `login`
+ * that found a valid cached basic token used to return on the cache rung and
+ * report `authenticated` with elevated still missing, which left the user in a
+ * loop with no exit: the command that needs elevated says "run login", login
+ * says "authenticated", the command fails identically, forever.
+ *
+ * When elevated is confirmed missing we escalate through the SAME
+ * `{ force: true }` rung the `--force` flag uses. That matters: the browser
+ * adapter has its own `freshCachedToken` probe that short-circuits the dance
+ * when a valid token is on disk, and only the forced path suppresses it — a
+ * hand-rolled re-capture here would silently no-op (LESSONS 2026-07-13).
+ *
+ * Supersedes the 2026-07-13 decision that `login` is a slim confirmation and
+ * `--force` the only re-capture mechanism: correct about the mechanism, but it
+ * left the signpost pointing at a command that could not do the job.
+ */
 declare const execute: (auth: AuthManager, options?: {
     force?: boolean;
 }) => Promise<Result<string, import("../../infra/auth.js").AuthError>>;

package/dist/use-cases/commands/mail-message-select.d.ts

@@ -0,0 +1 @@
+export declare const MAIL_MESSAGE_DEFAULT_SELECT = "id,subject,from,toRecipients,ccRecipients,receivedDateTime,hasAttachments,isRead,importance,bodyPreview,conversationId";

package/dist/use-cases/commands/mail-quote-stripper.d.ts

@@ -1,19 +1,15 @@
+import { z } from 'zod';
+import type { CommandOptionMeta } from './command-types.js';
 /**
- * Strips quoted reply chains / forwarded-message blocks from an Outlook or
- * Gmail HTML email body so long threads don't duplicate quoted content into the
- * model's context. Conservative: truncates the body at the EARLIEST well-known
- * reply/forward boundary marker and replaces the tail with a single visible
- * placeholder — nothing is removed silently, and `--keep-quoted true` on
- * `convert-mail-to-markdown` restores the full body. Pure string transform.
- *
- * Only structural, vendor-specific markers are matched (never a bare
- * `<blockquote>`, which legitimate content uses too):
- *   - Outlook desktop / OWA reply+forward header block: `<div id="divRplyFwdMsg">`
- *   - Outlook "type above this line" boundary:           `<div id="appendonsend">`
- *   - Outlook mobile reference container:                `<div id="mail-editor-reference-message-container">`
- *   - Outlook classic separator:                         `<hr id="stopSpelling">`
- *   - Gmail quote container:                             `<div class="gmail_quote">` / `<blockquote class="gmail_quote">`
+ * Index where the quoted history begins in an HTML body, or -1 when the body
+ * quotes nothing. Earliest of the structural markers merged with the widened
+ * confirmed-header index. Exported because the draft-comment splicer needs the
+ * same cut to place a reply ABOVE the quote without disturbing it — the stripper
+ * throws the tail away, the splicer keeps it, but both agree on where it starts.
  */
+declare const findQuoteBoundary: (html: string) => number;
+/** The plain-text counterpart of `findQuoteBoundary`, for `contentType === 'text'` bodies. */
+declare const findPlainTextQuoteBoundary: (text: string) => number;
 declare const stripQuotedReplies: (html: string) => {
     readonly html: string;
     readonly stripped: boolean;
@@ -22,4 +18,9 @@ declare const stripQuotedPlainText: (text: string) => {
     readonly text: string;
     readonly stripped: boolean;
 };
-export { stripQuotedPlainText, stripQuotedReplies };
+declare const keepQuotedSchemaField: z.ZodOptional<z.ZodEnum<{
+    true: "true";
+    false: "false";
+}>>;
+declare const keepQuotedOption: CommandOptionMeta;
+export { findPlainTextQuoteBoundary, findQuoteBoundary, keepQuotedOption, keepQuotedSchemaField, stripQuotedPlainText, stripQuotedReplies };

package/dist/use-cases/commands/markdown-dispatch.d.ts

@@ -11,13 +11,14 @@ type BytesToMarkdownOptions = {
     readonly includeMetadata?: boolean;
     readonly maxCells?: number;
     readonly inlineImages?: boolean;
+    readonly keepQuoted?: boolean;
     readonly depth?: number;
 };
 declare const NESTED_HINTS: ConversionHints;
 /**
  * The single extension→converter dispatch for every markdown command, operating on
  * bytes already in hand: download-drive-item-as-markdown fetches them, convert-mail
- * decodes the attachment, convert-drive-item-zip unpacks the entry. Loop/Fluid/
+ * decodes the attachment, convert-drive-item-zip-to-markdown unpacks the entry. Loop/Fluid/
  * Whiteboard (`?format=html`) need a Graph round-trip and are handled by the drive
  * caller BEFORE this — they never reach here. An Outlook `.msg` is rendered to markdown
  * (headers + body) with each of its own attachments recursed through this dispatch.

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

@@ -10,6 +10,14 @@ import type { ParsedMsg } from '../../infra/msg-reader-adapter.js';
  * user asked ("maybe same way as zip"). Unconvertible attachments (images, binaries)
  * are listed with the dispatch's note instead of failing the whole message.
  *
+ * The body goes through the same two passes `convert-mail-to-markdown` applies to a
+ * Graph mail body (they share the helpers): the quoted reply chain is stripped by
+ * default — `keepQuoted` restores it, and every command that can hand a `.msg` to
+ * this renderer exposes that as `--keep-quoted`, so the marker's remedy always
+ * works — and any `cid:` image becomes a readable placeholder. A `.msg` carries no
+ * contentId on its attachments, so embedding is impossible here and the placeholder
+ * falls back to the img alt text or the cid's filename prefix.
+ *
  * `recurse` is the attachment converter injected by `markdown-dispatch` (its own
  * `bytesToMarkdown`, with the recursion depth incremented). Injecting it — rather
  * than importing `bytesToMarkdown` here — keeps this use-case off the dispatch's
@@ -20,9 +28,10 @@ import type { ParsedMsg } from '../../infra/msg-reader-adapter.js';
 declare const MAX_MSG_DEPTH = 3;
 type MsgToMarkdownOptions = {
     readonly depth?: number;
+    readonly keepQuoted?: boolean;
 };
 type MsgAttachmentConverter = (bytes: Uint8Array, filename: string) => Promise<Result<unknown, GraphError>>;
-declare const renderMsg: (msg: ParsedMsg, depth: number, recurse: MsgAttachmentConverter) => Promise<string>;
+declare const renderMsg: (msg: ParsedMsg, opts: MsgToMarkdownOptions, recurse: MsgAttachmentConverter) => Promise<string>;
 declare const msgToMarkdown: (bytes: Uint8Array, opts: MsgToMarkdownOptions, recurse: MsgAttachmentConverter) => Promise<Result<unknown, GraphError>>;
 export { MAX_MSG_DEPTH, msgToMarkdown, renderMsg };
 export type { MsgAttachmentConverter, MsgToMarkdownOptions };

package/dist/use-cases/commands/odata-query.d.ts

@@ -9,6 +9,20 @@ declare const odataQuerySchema: z.ZodObject<{
     expand: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type ODataQueryParams = z.infer<typeof odataQuerySchema>;
+/**
+ * Embed a user-supplied value inside an OData single-quoted string literal
+ * (`$filter=mail eq '<here>'`, `contains(title,'<here>')`, `search(q='<here>')`).
+ * Two steps, in this order:
+ * 1. double any `'` — OData's string-literal escape, so the value cannot
+ *    terminate the literal early;
+ * 2. percent-encode — graph-client concatenates command paths verbatim, so an
+ *    un-encoded value corrupts the query string. `&`/`#` truncate it outright,
+ *    and a raw `+` is decoded back to a SPACE server-side, which silently
+ *    matches nothing (base64 conversationIds and plus-addressed emails both
+ *    carry `+`). encodeURIComponent leaves `'` unreserved, so the doubled
+ *    quote survives as the escape OData expects.
+ */
+declare const odataStringLiteral: (value: string) => string;
 declare const appendOData: (path: string, params: ODataQueryParams) => string;
 declare const odataQueryOptions: ReadonlyArray<CommandOptionMeta>;
 /**
@@ -86,5 +100,5 @@ declare const selectOnlyShape: Pick<{
     expand: z.ZodOptional<z.ZodString>;
 }, "select">;
 declare const selectOnlyOptions: readonly CommandOptionMeta[];
-export { appendOData, filterSelectOptions, filterSelectSchema, noSkipOptions, noSkipShape, odataQueryOptions, odataQuerySchema, pickODataOptions, pickODataShape, selectExpandOptions, selectExpandSchema, selectOnlyOptions, selectOnlyShape, topOnlyOptions, topOnlyShape, };
+export { appendOData, filterSelectOptions, filterSelectSchema, noSkipOptions, noSkipShape, odataQueryOptions, odataQuerySchema, odataStringLiteral, pickODataOptions, pickODataShape, selectExpandOptions, selectExpandSchema, selectOnlyOptions, selectOnlyShape, topOnlyOptions, topOnlyShape, };
 export type { FilterSelectParams, ODataKey, ODataQueryParams, SelectExpandParams };

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

@@ -5,6 +5,7 @@ type OfficeToMarkdownOptions = FetchOptions & {
     readonly includeMetadata?: boolean;
     readonly inlineImages?: boolean;
     readonly maxCells?: number;
+    readonly keepQuoted?: boolean;
 };
 declare const officeToMarkdown: (graph: GraphClient, contentPath: string, filename: string, opts?: OfficeToMarkdownOptions) => Promise<Result<unknown, GraphError>>;
 export { officeToMarkdown };

package/dist/use-cases/commands/read-mail-attachment.d.ts

@@ -9,6 +9,10 @@ declare const schema: z.ZodObject<{
         true: "true";
         false: "false";
     }>>;
+    keepQuoted: 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/resolve-command.d.ts

@@ -0,0 +1,25 @@
+import type { Result } from '../../domain/result.js';
+import type { Command } from './command-types.js';
+/**
+ * Name -> command lookup that also honours `meta.commandAliases`.
+ *
+ * The CLI gets alias resolution for free from commander (`commandDef.alias(...)`
+ * in `cli.ts`), so nothing needed this until a second front end appeared. The
+ * MCP gateway has no commander, and its three command-taking tools
+ * (`get-command-docs`, `run-command`, `run-write-command`) each need the same
+ * lookup — Rule of Three, so it lives here rather than inline.
+ *
+ * Returns the CANONICAL name alongside the command so every downstream concern
+ * (docs rendering, the `mutates` read/write gate, error messages) keys off one
+ * spelling regardless of which one the caller used.
+ */
+export type ResolveCommandError = {
+    readonly type: 'unknown_command';
+    readonly name: string;
+    readonly available: ReadonlyArray<string>;
+};
+export type ResolvedCommand = {
+    readonly name: string;
+    readonly command: Command;
+};
+export declare const resolveCommand: (registry: Readonly<Record<string, Command>>, name: string) => Result<ResolvedCommand, ResolveCommandError>;

package/dist/use-cases/commands/search-all-files.d.ts

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

package/dist/use-cases/commands/search-escape.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Wire-safe builder for Graph `$search=` KQL clauses. graph-client
+ * concatenates command paths verbatim (`https://graph.microsoft.com/v1.0${path}`)
+ * with no percent-encoding pass, so a raw `&`, `#`, `%`, or `+` inside a user
+ * query corrupts the query string on the wire: a live ` & ` truncated the KQL
+ * mid-phrase (`$search="subject:"Contoso A2` reached Graph). Values are
+ * percent-encoded here, at the only layer that knows which part of the path
+ * is data.
+ *
+ * The sibling concern — a value inside a single-quoted OData literal
+ * (`$filter=x eq '…'`, `contains(…)`, `search(q='…')`) — is
+ * `odataStringLiteral` in odata-query.ts, which owns OData query construction.
+ */
+/**
+ * Build a `$search=` KQL clause: escape embedded double quotes as `\"`
+ * (Graph's documented KQL escaping, so `subject:"multi word"` and whole
+ * `"phrase"` queries become phrase matches instead of a BadRequest), wrap the
+ * expression in the double quotes Graph requires, then percent-encode the
+ * value. Backslashes are NOT pre-escaped: raw quotes are the documented
+ * input contract and backslash has no other KQL meaning here.
+ */
+declare const kqlSearchClause: (query: string) => string;
+export { kqlSearchClause };

package/dist/use-cases/commands/signature-extractor.d.ts

@@ -0,0 +1,2 @@
+declare const extractSignatureBlock: (html: string) => string | undefined;
+export { extractSignatureBlock };

package/dist/use-cases/commands/tenant-option.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { TenantId } from '../../domain/tenant-id.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { CommandOptionMeta } from './command-types.js';
+/**
+ * `--tenant-id`: read a file that lives in a tenant you are only a GUEST in.
+ *
+ * Without it, such a read dies at `401 invalidAudienceUri` — home-tenant Graph
+ * cannot mint a SharePoint token for a foreign tenant, so no home-tier token can
+ * reach it. Unlike `resolve-drive-share-link`, these commands cannot recover on
+ * their own: they hold only a `driveId` and an `itemId`, and NEITHER carries a
+ * tenant. The sharing URL does, which is why `resolve-drive-share-link` returns
+ * the `tenantId` for this flag to consume.
+ *
+ * OPTIONAL, always. That is not a detail — `required: true` compiles straight to
+ * commander's `.requiredOption()`, so an optional flag is what keeps the
+ * `CommandMeta` contract untouched and every existing invocation working.
+ */
+declare const tenantIdShape: {
+    tenantId: z.ZodOptional<z.ZodString>;
+};
+declare const tenantIdSchema: z.ZodObject<{
+    tenantId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const TENANT_ID_OPTION: CommandOptionMeta;
+/**
+ * Route a JSON GET to the right identity: the home token normally, a partner
+ * tenant's guest token when `--tenant-id` was given.
+ *
+ * The guest tier is a RUNTIME choice, not a static one like `elevated` — the same
+ * command uses either, depending on this flag. That is why the builders route
+ * here instead of growing guest twins (which would take 10 builders to 14+, and
+ * would still not express "it depends on the argument").
+ */
+declare const routeGet: (graph: GraphClient, path: string, rawTenantId: string | undefined) => Promise<Result<unknown, GraphError>>;
+/**
+ * Validate a caller-supplied tenant id at the boundary. The value reaches an
+ * authority URL whose POST carries the refresh token, so it is branded rather
+ * than trusted (hard rule 12); a bad one must fail here with a readable message,
+ * not further in.
+ */
+declare const brandTenantId: (raw: string) => Result<TenantId, GraphError>;
+export { TENANT_ID_OPTION, brandTenantId, routeGet, tenantIdSchema, tenantIdShape };

package/dist/use-cases/commands/update-mail-draft.d.ts

@@ -4,6 +4,7 @@ declare const schema: z.ZodObject<{
     messageId: z.ZodString;
     subject: z.ZodOptional<z.ZodString>;
     bodyContent: z.ZodOptional<z.ZodString>;
+    comment: z.ZodOptional<z.ZodString>;
     bodyContentType: z.ZodOptional<z.ZodEnum<{
         Text: "Text";
         HTML: "HTML";

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

@@ -3,9 +3,9 @@ import type { GraphError } from '../../infra/graph-client.js';
 import type { MediaEnvelope } from './media-files.js';
 /**
  * Shared "unzip + convert every contained file" core behind
- * `convert-drive-item-zip` (a OneDrive / SharePoint .zip),
- * `convert-mail-attachment-zip` (an Outlook .zip attachment), and
- * `convert-local-file` (a .zip on disk). Each entry is run through the same
+ * `convert-drive-item-zip-to-markdown` (a OneDrive / SharePoint .zip),
+ * `convert-mail-attachment-zip-to-markdown` (an Outlook .zip attachment), and
+ * `convert-local-file-to-markdown` (a .zip on disk). Each entry is run through the same
  * `bytesToMarkdown` dispatch the markdown commands use; an entry the dispatch
  * can't convert (image, binary, nested archive, scanned PDF) is LISTED with a
  * note instead of failing the whole archive. Notes use the container-neutral
@@ -27,6 +27,11 @@ type ZipArchiveResult = {
     readonly totalEntries?: number;
     readonly files: ReadonlyArray<FileResult>;
 };
-declare const convertZipArchive: (bytes: Uint8Array, includeMetadata: boolean, includeImages?: boolean) => Promise<Result<ZipArchiveResult, GraphError>>;
+type ZipArchiveOptions = {
+    readonly includeMetadata: boolean;
+    readonly includeImages?: boolean;
+    readonly keepQuoted?: boolean;
+};
+declare const convertZipArchive: (bytes: Uint8Array, opts: ZipArchiveOptions) => Promise<Result<ZipArchiveResult, GraphError>>;
 export { convertZipArchive, MAX_ENTRIES };
-export type { FileResult, ZipArchiveResult };
+export type { FileResult, ZipArchiveOptions, ZipArchiveResult };

package/dist/use-cases/ports/filesystem.d.ts

@@ -11,7 +11,7 @@ export type FileSystemError = {
 export type FileSystem = {
     readonly readJson: <T>(path: string) => Promise<Result<T, FileSystemError>>;
     /**
-     * Read a file's raw bytes. Used by `convert-local-file` to feed a local
+     * Read a file's raw bytes. Used by `convert-local-file-to-markdown` to feed a local
      * document into the same conversion dispatch the Graph-backed commands use.
      */
     readonly readBytes: (path: string) => Promise<Result<Uint8Array, FileSystemError>>;