ask-marcel-office-cli 1.0.0 → 1.5.0

package/dist/use-cases/commands/onenote-metadata.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Renders the `## OneNote metadata` block appended to `get-onenote-page-as-markdown`
+ * output under `--include-metadata true`. Mirrors the docx/xlsx/odf metadata-append
+ * pattern: a fenced section listing the page's title, created / last-modified
+ * timestamps, and the parent section + notebook names (expanded by the command).
+ * Pure formatter — every field is optional and omitted when absent.
+ */
+type OnenotePage = {
+    readonly title?: string;
+    readonly createdDateTime?: string;
+    readonly lastModifiedDateTime?: string;
+    readonly parentSection?: {
+        readonly displayName?: string;
+    };
+    readonly parentNotebook?: {
+        readonly displayName?: string;
+    };
+};
+declare const formatOnenoteMetadata: (page: OnenotePage) => string;
+export { formatOnenoteMetadata };
+export type { OnenotePage };

package/dist/use-cases/commands/onenote-resource-embedder.d.ts

@@ -0,0 +1,3 @@
+import type { GraphClient } from '../../infra/graph-client.js';
+declare const embedOnenoteResources: (graph: GraphClient, html: string) => Promise<string>;
+export { embedOnenoteResources };

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

@@ -0,0 +1,16 @@
+/**
+ * Shared markdown render primitives for the per-format metadata blocks
+ * (docx, xlsx, …). Sections with no entries emit `_(none)_` so the output
+ * stays grep-stable — an LLM can ask "is there a Comments section?" and get
+ * a yes/no answer without ambiguity.
+ *
+ * Pipe characters in cell values are escaped as `\|` so the rendered tables
+ * stay valid even when property values or comment bodies contain literal pipes.
+ */
+declare const NONE = "_(none)_";
+declare const escapeCell: (s: string) => string;
+declare const renderKv: (props: Readonly<Record<string, string>>) => string;
+declare const renderTable: (rows: ReadonlyArray<ReadonlyArray<string>>, headers: ReadonlyArray<string>) => string;
+declare const renderBullets: (items: ReadonlyArray<string>) => string;
+declare const renderMacros: (macros: ReadonlyArray<string>) => string;
+export { escapeCell, NONE, renderBullets, renderKv, renderMacros, renderTable };

package/dist/use-cases/commands/ooxml-metadata.d.ts

@@ -0,0 +1,23 @@
+import type { OoxmlZip } from '../../infra/ooxml-zip-adapter.js';
+/**
+ * The OOXML package-level metadata that is identical across .docx / .xlsx /
+ * .pptx: the three `docProps/*` property parts and every external
+ * relationship in the package. Per-format modules (docx-metadata,
+ * xlsx-metadata, …) compose these with their own body-specific extractors.
+ */
+type CustomProp = {
+    readonly name: string;
+    readonly value: string;
+};
+type ExternalRel = {
+    readonly source: string;
+    readonly type: string;
+    readonly target: string;
+};
+declare const extractCoreProps: (zip: OoxmlZip) => Readonly<Record<string, string>>;
+declare const extractAppProps: (zip: OoxmlZip) => Readonly<Record<string, string>>;
+declare const extractCustomProps: (zip: OoxmlZip) => ReadonlyArray<CustomProp>;
+declare const extractExternalRels: (zip: OoxmlZip) => ReadonlyArray<ExternalRel>;
+declare const extractMacros: (zip: OoxmlZip) => ReadonlyArray<string>;
+export { extractAppProps, extractCoreProps, extractCustomProps, extractExternalRels, extractMacros };
+export type { CustomProp, ExternalRel };

package/dist/use-cases/commands/ooxml-xml-walker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tiny generic walkers over a fast-xml-parser tree. OOXML is namespace-
+ * heavy (`w:`, `cp:`, `dc:`, `dcterms:`, `vt:`, `w15:`, `x:`, `p:`, ...) and
+ * the only traversal primitives we need are: find-every-element-by-tag-name,
+ * read a single attribute, read the leaf text content. Keeping these here
+ * lets the per-format metadata modules focus on what to extract, not how to
+ * traverse.
+ *
+ * fast-xml-parser tree shape:
+ *   - element names are object keys (with `w:` etc. prefix preserved)
+ *   - attributes are keys prefixed with `@_` (e.g. `@_w:val`, `@_TargetMode`)
+ *   - text content sits under `#text` when the element also has attributes,
+ *     OR directly as a string when the element has only text and no attrs
+ *   - repeated same-named children come as an array; single occurrences as
+ *     a bare object — every walker must handle both shapes
+ */
+type XmlObject = Record<string, unknown>;
+declare const parseXml: (xml: string | undefined) => unknown;
+declare const findAll: (root: unknown, tagName: string) => ReadonlyArray<XmlObject>;
+declare const textOf: (node: unknown) => string;
+declare const attrOf: (node: XmlObject, name: string) => string;
+/**
+ * Yield each occurrence of `tagName` inside `node` as its own text value.
+ * Used for leaf-text elements like `<w:instrText>` where each instance is a
+ * distinct entry (one MERGEFIELD per occurrence) — unlike collectText, which
+ * flattens every match into a single string for "the visible text of this run".
+ */
+declare const findAllTexts: (root: unknown, tagName: string) => ReadonlyArray<string>;
+/**
+ * Concatenate the text content of every element matching `tagName` inside `node`,
+ * regardless of nesting depth. Used to flatten a `<w:p>` (or `<w:ins>` / `<w:comment>`)
+ * down to its visible text by gathering every `<w:t>` (or `<w:delText>`) descendant.
+ */
+declare const collectText: (node: unknown, tagName: string) => string;
+export { attrOf, collectText, findAll, findAllTexts, parseXml, textOf };
+export type { XmlObject };

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

@@ -0,0 +1,5 @@
+/**
+ * `--drive-id` description for every generic OneDrive / SharePoint drive-item
+ * command. Always points the caller at how to obtain a drive id.
+ */
+export declare const DRIVE_ID_DESCRIPTION = "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library.";

package/dist/use-cases/commands/output-path.d.ts

@@ -33,5 +33,28 @@ export type OutputPathError = {
     readonly type: 'passthrough_extension_mismatch';
     readonly contentType: string;
     readonly requestedExtension: string;
+} | {
+    readonly type: 'inline_too_large';
+    readonly base64Length: number;
+};
+export type OutputDirError = {
+    readonly type: 'no_media';
+} | {
+    readonly type: 'empty_path';
+} | {
+    readonly type: 'write_failed';
+    readonly message: string;
 };
 export declare const persistIfRequested: (fs: FileSystem, outputPath: string | undefined, data: unknown) => Promise<Result<unknown, OutputPathError>>;
+/**
+ * Sibling of `persistIfRequested` for the global `--output-dir` flag. When a
+ * command returns a `media` array (`{ count, media: [{ path, base64, ... }] }`,
+ * from the image-extraction commands) and `--output-dir` is set, write each
+ * image to `<dir>/<flattened-path>` and replace its `base64` with `savedTo`.
+ * The media `path` is flattened (`pdf/page2/Im0.png` → `pdf_page2_Im0.png`)
+ * rather than reduced to its basename, because PDF page-image keys (`Im0`, …)
+ * repeat across pages — `basename` alone would collide and silently overwrite.
+ * The filesystem port auto-creates the directory. Anything without a media
+ * array returns `no_media` so the CLI can surface a clear error.
+ */
+export declare const persistMediaIfRequested: (fs: FileSystem, outputDir: string | undefined, data: unknown) => Promise<Result<unknown, OutputDirError>>;

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

@@ -0,0 +1,19 @@
+import type { Result } from '../../domain/result.js';
+import type { GraphError } from '../../infra/graph-client.js';
+type PdfTextEnvelope = {
+    readonly contentType: 'text/plain';
+    readonly size: number;
+    readonly text: string;
+    readonly pageCount: number;
+};
+/**
+ * Convert a PDF to a plain-text envelope by extracting its text layer (via unpdf).
+ * A born-digital PDF yields its reading-order text; a scanned / image-only PDF has
+ * no text layer, so the caller's `noTextHint` (pointing at the matching *-as-pdf
+ * command + a vision model) is returned as a 415 rather than an empty body. Output
+ * is text/plain, not structured markdown — pdfjs flattens layout into reading order.
+ * `size` is the byte length of the produced text (what `--output-path` writes),
+ * consistent with the other converters — NOT the source PDF's byte count.
+ */
+declare const pdfToMarkdown: (bytes: Uint8Array, noTextHint: string) => Promise<Result<PdfTextEnvelope, GraphError>>;
+export { pdfToMarkdown };

package/dist/use-cases/commands/pptx-comments.d.ts

@@ -0,0 +1,24 @@
+import type { OoxmlZip } from '../../infra/ooxml-zip-adapter.js';
+/**
+ * PowerPoint comments come in two formats: legacy (`ppt/commentAuthors.xml`
+ * authors by integer id + `ppt/comments/comment*.xml` `<p:cm authorId dt>`
+ * with `<p:text>` body) and modern (`ppt/authors.xml` authors by GUID +
+ * `ppt/comments/*.xml` `<p188:cm authorId created>` with DrawingML `<a:t>`
+ * body). Both are scanned; authors are resolved by id in either scheme.
+ * Modern-comment support is best-effort against the p188 (2018/8) schema.
+ */
+type CommentAuthor = {
+    readonly id: string;
+    readonly name: string;
+    readonly initials: string;
+};
+type PptxComment = {
+    readonly author: string;
+    readonly date: string;
+    readonly text: string;
+    readonly slide?: string;
+};
+declare const extractCommentAuthors: (zip: OoxmlZip) => ReadonlyArray<CommentAuthor>;
+declare const extractComments: (zip: OoxmlZip, authors: ReadonlyArray<CommentAuthor>) => ReadonlyArray<PptxComment>;
+export { extractCommentAuthors, extractComments };
+export type { CommentAuthor, PptxComment };

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

@@ -0,0 +1,3 @@
+import type { PptxMetadata } from './pptx-metadata.js';
+declare const formatPptxMetadata: (meta: PptxMetadata) => string;
+export { formatPptxMetadata };

package/dist/use-cases/commands/pptx-metadata.d.ts

@@ -0,0 +1,33 @@
+import type { Result } from '../../domain/result.js';
+import type { GraphError } from '../../infra/graph-client.js';
+import type { CustomProp, ExternalRel } from './ooxml-metadata.js';
+import type { CommentAuthor, PptxComment } from './pptx-comments.js';
+import type { Slide } from './pptx-slides.js';
+/**
+ * Pulls the side-channel content out of a .pptx zip — everything a user can
+ * author that the rendered slide PDF never shows: core / app / custom doc
+ * properties, external relationships, slide tags (key/value), comment authors
+ * and comments (legacy + modern), and per-slide title / speaker notes / hidden
+ * flag. Package-level parts come from the shared ooxml-metadata module; this
+ * file owns the presentation-specific parts.
+ */
+type PropMap = Readonly<Record<string, string>>;
+type SlideTag = {
+    readonly source: string;
+    readonly name: string;
+    readonly value: string;
+};
+type PptxMetadata = {
+    readonly core: PropMap;
+    readonly app: PropMap;
+    readonly custom: ReadonlyArray<CustomProp>;
+    readonly externalRels: ReadonlyArray<ExternalRel>;
+    readonly slideTags: ReadonlyArray<SlideTag>;
+    readonly commentAuthors: ReadonlyArray<CommentAuthor>;
+    readonly comments: ReadonlyArray<PptxComment>;
+    readonly slides: ReadonlyArray<Slide>;
+    readonly macros: ReadonlyArray<string>;
+};
+declare const extractPptxMetadata: (bytes: Uint8Array) => Promise<Result<PptxMetadata, GraphError>>;
+export { extractPptxMetadata };
+export type { CommentAuthor, PptxComment, PptxMetadata, Slide, SlideTag };

package/dist/use-cases/commands/pptx-slides.d.ts

@@ -0,0 +1,17 @@
+import type { OoxmlZip } from '../../infra/ooxml-zip-adapter.js';
+/**
+ * Per-slide extraction: the hidden flag (`<p:sld show="0">`), the title
+ * placeholder text, and the speaker notes resolved through the slide's
+ * relationship part. Speaker notes are the headline pptx side-channel —
+ * presenter-authored text that never appears on the rendered slide.
+ */
+type Slide = {
+    readonly name: string;
+    readonly hidden: boolean;
+    readonly title: string;
+    readonly notes: string;
+    readonly text: string;
+};
+declare const extractSlides: (zip: OoxmlZip) => ReadonlyArray<Slide>;
+export { extractSlides };
+export type { Slide };

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

@@ -0,0 +1,7 @@
+import type { Result } from '../../domain/result.js';
+import type { GraphError } from '../../infra/graph-client.js';
+import type { MarkdownEnvelope } from './docx-to-markdown.js';
+declare const pptxToMarkdown: (bytes: Uint8Array, options?: {
+    readonly includeMetadata?: boolean;
+}) => Promise<Result<MarkdownEnvelope, GraphError>>;
+export { pptxToMarkdown };

package/dist/use-cases/commands/read-mail-attachment.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<{
+    messageId: 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/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 };

package/dist/use-cases/commands/resolve-drive-share-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 };

package/dist/use-cases/commands/resolve-mail-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 };

package/dist/use-cases/commands/resolve-teams-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 };

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

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

package/dist/use-cases/commands/search-index-total.d.ts

@@ -0,0 +1,3 @@
+import type { GraphClient } from '../../infra/graph-client.js';
+declare const searchIndexTotal: (graph: GraphClient, entityType: string, queryString?: string) => Promise<number | undefined>;
+export { searchIndexTotal };

package/dist/use-cases/commands/search-sharepoint-sites-by-name.d.ts

@@ -1,4 +1,5 @@
-import type { CommandMeta } from './command-types.js';
-declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: import("./command-types.js").CommandSchema;
+declare const execute: Command['execute'];
 declare const meta: CommandMeta;
 export { execute, meta, schema };

package/dist/use-cases/commands/sharepoint-link-extractor.d.ts

@@ -1,14 +1,19 @@
-/**
- * Pure helpers for `extract-sharepoint-links-in-mail`.
- *
- * `extractSharepointUrls(htmlBody)` finds every `https://*.sharepoint.com/...`
- * URL inside an HTML mail body — both `<a href=...>` and bare-text
- * occurrences — and returns the deduplicated list.
- *
- * `buildShareToken(url)` encodes a URL for Graph's `/shares/{token}`
- * resolver per [shares-get](https://learn.microsoft.com/en-us/graph/api/shares-get):
- * `u!` + base64url(url) with no padding.
- */
+import type { GraphClient } from '../../infra/graph-client.js';
+type ResolvedLink = {
+    readonly url: string;
+    readonly driveId?: string;
+    readonly itemId?: string;
+    readonly name?: string;
+    readonly webUrl?: string;
+    readonly error?: string;
+};
+type ResolvedLinks = {
+    readonly links: ReadonlyArray<ResolvedLink>;
+    readonly truncated: boolean;
+    readonly skippedCount: number;
+};
 declare const extractSharepointUrls: (htmlBody: string) => ReadonlyArray<string>;
 declare const buildShareToken: (url: string) => string;
-export { buildShareToken, extractSharepointUrls };
+declare const resolveSharepointUrls: (graph: GraphClient, urls: ReadonlyArray<string>) => Promise<ResolvedLinks>;
+export { buildShareToken, extractSharepointUrls, resolveSharepointUrls };
+export type { ResolvedLink, ResolvedLinks };

package/dist/use-cases/commands/text-passthrough.d.ts

@@ -18,7 +18,20 @@
  *     The user wanted a PDF and the source IS a PDF, so return its
  *     bytes directly.
  */
-declare const PLAIN_TEXT_EXTENSIONS: ReadonlySet<string>;
+declare const extensionOf: (name: string) => string;
 declare const isPlainTextFilename: (name: string) => boolean;
 declare const isPdfSource: (name: string) => boolean;
-export { isPdfSource, isPlainTextFilename, PLAIN_TEXT_EXTENSIONS };
+/**
+ * Content-sniff for text — decode bytes STRICTLY as UTF-8. Returns the decoded
+ * string when the bytes are valid UTF-8, `undefined` when they are not (i.e.
+ * binary). The conversion / content commands use this instead of trusting a
+ * file extension: it detects any text file regardless of name AND can never
+ * mangle binary into `�` (the non-fatal decoder's silent corruption — the bug
+ * a binary file named `.txt` triggered). Non-UTF-8-encoded text (UTF-16, etc.)
+ * is reported as binary, which is faithful (base64) rather than lossy.
+ *
+ * `{ fatal: true }` makes `decode` throw on the first invalid sequence; the
+ * try/catch is a pure-domain fallback around a native synchronous thrower.
+ */
+declare const decodeUtf8Text: (bytes: Uint8Array) => string | undefined;
+export { decodeUtf8Text, extensionOf, isPdfSource, isPlainTextFilename };

package/dist/use-cases/commands/todo-parse-uri-rewrite.d.ts

@@ -0,0 +1,7 @@
+import type { GraphError } from '../../infra/graph-client.js';
+type TodoQuirkParams = {
+    readonly select?: string;
+    readonly orderby?: string;
+};
+declare const rewriteTodoTitleQuirk: (error: GraphError, params: TodoQuirkParams) => GraphError | undefined;
+export { rewriteTodoTitleQuirk };

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

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    messageId: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    bodyContent: z.ZodOptional<z.ZodString>;
+    bodyContentType: z.ZodOptional<z.ZodEnum<{
+        Text: "Text";
+        HTML: "HTML";
+    }>>;
+    toRecipients: z.ZodOptional<z.ZodString>;
+    ccRecipients: z.ZodOptional<z.ZodString>;
+    bccRecipients: z.ZodOptional<z.ZodString>;
+    importance: z.ZodOptional<z.ZodEnum<{
+        Low: "Low";
+        Normal: "Normal";
+        High: "High";
+    }>>;
+}, z.core.$strip>;
+declare const execute: Command['execute'];
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/version-id.d.ts

@@ -1,16 +1,17 @@
 /**
  * Graph's historical-version endpoints template `{version-id}` as a string
  * that must look like a stringified float (`"79.0"`, `"4.0"`). An LLM
- * (reasonably) types `79`, and the response is wildly inconsistent across
- * the three sibling commands:
+ * (reasonably) types `79`, and Graph's response is wildly inconsistent
+ * across the three internal pipelines that the consolidated
+ * `download-drive-item-version` command dispatches to:
  *
- *   - download-drive-item-version-content        → `invalidRequest`
- *   - download-drive-item-version-as-markdown    → `invalidRequest`
- *   - download-drive-item-version-as-pdf         → accepts (Graph quirk)
+ *   - --format original  → `invalidRequest`
+ *   - --format markdown  → `invalidRequest`
+ *   - --format pdf       → accepts (Graph quirk)
  *
  * Audit round-6 §1.4 caught the inconsistency. Normalize at the CLI
  * boundary: a pure-integer version-id gets `.0` appended before path
- * substitution, so all three commands accept both spellings.
+ * substitution, so all three formats accept both spellings.
  *
  * Already-floated values (`79.0`, `12.5`, `4.1`) and non-numeric values
  * (a bad input the schema will then reject) pass through unchanged.

package/dist/use-cases/commands/xlsx-comments.d.ts

@@ -0,0 +1,29 @@
+import type { OoxmlZip } from '../../infra/ooxml-zip-adapter.js';
+/**
+ * Workbook annotations + the identities behind them. xlsx has two comment
+ * formats: legacy cell comments (xl/comments*.xml, author by index into an
+ * <authors> list) and modern threaded comments (xl/threadedComments/*, author
+ * by personId resolved through xl/persons/person.xml). Both are user-authored
+ * and invisible in the value-rendered body.
+ */
+type CellComment = {
+    readonly cell: string;
+    readonly author: string;
+    readonly text: string;
+};
+type ThreadedComment = {
+    readonly cell: string;
+    readonly author: string;
+    readonly date: string;
+    readonly text: string;
+};
+type Person = {
+    readonly id: string;
+    readonly displayName: string;
+    readonly userId: string;
+};
+declare const extractPeople: (zip: OoxmlZip) => ReadonlyArray<Person>;
+declare const extractLegacyComments: (zip: OoxmlZip) => ReadonlyArray<CellComment>;
+declare const extractThreadedComments: (zip: OoxmlZip, people: ReadonlyArray<Person>) => ReadonlyArray<ThreadedComment>;
+export { extractLegacyComments, extractPeople, extractThreadedComments };
+export type { CellComment, Person, ThreadedComment };

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

@@ -0,0 +1,3 @@
+import type { XlsxMetadata } from './xlsx-metadata.js';
+declare const formatXlsxMetadata: (meta: XlsxMetadata) => string;
+export { formatXlsxMetadata };

package/dist/use-cases/commands/xlsx-metadata.d.ts

@@ -0,0 +1,39 @@
+import type { Result } from '../../domain/result.js';
+import type { GraphError } from '../../infra/graph-client.js';
+import type { CustomProp, ExternalRel } from './ooxml-metadata.js';
+import type { CellComment, Person, ThreadedComment } from './xlsx-comments.js';
+/**
+ * Pulls the side-channel content out of a .xlsx zip — everything a user can
+ * author that the value-rendered markdown body (cells per sheet) never shows:
+ * core / app / custom doc properties, external relationships, defined names
+ * (named ranges & formulas), hidden / very-hidden sheets, legacy cell
+ * comments, threaded comments, and the persons registry behind them.
+ *
+ * Package-level parts (docProps/*, every *.rels) come from the shared
+ * ooxml-metadata module; this file owns the workbook-specific parts.
+ */
+type PropMap = Readonly<Record<string, string>>;
+type DefinedName = {
+    readonly name: string;
+    readonly refersTo: string;
+    readonly hidden: boolean;
+};
+type Sheet = {
+    readonly name: string;
+    readonly state: string;
+};
+type XlsxMetadata = {
+    readonly core: PropMap;
+    readonly app: PropMap;
+    readonly custom: ReadonlyArray<CustomProp>;
+    readonly externalRels: ReadonlyArray<ExternalRel>;
+    readonly definedNames: ReadonlyArray<DefinedName>;
+    readonly hiddenSheets: ReadonlyArray<Sheet>;
+    readonly comments: ReadonlyArray<CellComment>;
+    readonly threadedComments: ReadonlyArray<ThreadedComment>;
+    readonly people: ReadonlyArray<Person>;
+    readonly macros: ReadonlyArray<string>;
+};
+declare const extractXlsxMetadata: (bytes: Uint8Array) => Promise<Result<XlsxMetadata, GraphError>>;
+export { extractXlsxMetadata };
+export type { CellComment, DefinedName, Person, Sheet, ThreadedComment, XlsxMetadata };

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

@@ -1,6 +1,13 @@
 import type { Result } from '../../domain/result.js';
 import type { GraphError } from '../../infra/graph-client.js';
 import type { MarkdownEnvelope } from './docx-to-markdown.js';
+type XlsxToMarkdownOptions = {
+    readonly includeMetadata?: boolean;
+    readonly maxCells?: number;
+};
 declare const csvToMarkdownTable: (csv: string) => string;
-declare const xlsxToMarkdown: (bytes: Uint8Array) => Result<MarkdownEnvelope, GraphError>;
-export { csvToMarkdownTable, xlsxToMarkdown };
+declare const renderCsvCapped: (csv: string, maxCells?: number) => string;
+declare const csvToMarkdownSection: (name: string, csv: string, maxCells?: number) => string;
+declare const xlsxToMarkdown: (bytes: Uint8Array, opts?: XlsxToMarkdownOptions) => Promise<Result<MarkdownEnvelope, GraphError>>;
+export { csvToMarkdownSection, csvToMarkdownTable, renderCsvCapped, xlsxToMarkdown };
+export type { XlsxToMarkdownOptions };

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

@@ -0,0 +1,30 @@
+import type { Result } from '../../domain/result.js';
+import type { GraphError } from '../../infra/graph-client.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
+ * `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
+ * NESTED_HINTS (QA-007): entries live INSIDE the zip, so caller-specific
+ * sibling-command pointers (`extract-drive-item-images`, …) cannot reach them.
+ */
+declare const MAX_ENTRIES = 100;
+type FileResult = {
+    readonly path: string;
+    readonly contentType?: string;
+    readonly size?: number;
+    readonly text?: string;
+    readonly note?: string;
+};
+type ZipArchiveResult = {
+    readonly count: number;
+    readonly truncated?: true;
+    readonly totalEntries?: number;
+    readonly files: ReadonlyArray<FileResult>;
+};
+declare const convertZipArchive: (bytes: Uint8Array, includeMetadata: boolean) => Promise<Result<ZipArchiveResult, GraphError>>;
+export { convertZipArchive, MAX_ENTRIES };
+export type { FileResult, ZipArchiveResult };

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

@@ -10,8 +10,18 @@ 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
+     * document into the same conversion dispatch the Graph-backed commands use.
+     */
+    readonly readBytes: (path: string) => Promise<Result<Uint8Array, FileSystemError>>;
     readonly writeText: (path: string, content: string) => Promise<Result<void, FileSystemError>>;
     readonly writeBytes: (path: string, bytes: Uint8Array) => Promise<Result<void, FileSystemError>>;
+    /**
+     * Restrict a file's permission bits (e.g. 0o600 on the token cache so
+     * other local users cannot read cached secrets — QA-001).
+     */
+    readonly chmod: (path: string, mode: number) => Promise<Result<void, FileSystemError>>;
     readonly deleteIfExists: (path: string) => Promise<Result<void, FileSystemError>>;
     /**
      * Recursively delete a directory (and all its contents). Used by `logout`