ask-marcel-office-cli 0.5.5 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (197) hide show
  1. package/CHANGELOG.md +92 -0
  2. package/README.md +147 -221
  3. package/dist/cli.js +99348 -14825
  4. package/dist/commands.json +5870 -789
  5. package/dist/composition/build-deps.d.ts +1 -0
  6. package/dist/composition/cli.d.ts +2 -0
  7. package/dist/domain/iso-datetime.d.ts +30 -0
  8. package/dist/index.js +97246 -13703
  9. package/dist/infra/auth.d.ts +61 -3
  10. package/dist/infra/browser-auth.d.ts +163 -1
  11. package/dist/infra/graph-client.d.ts +99 -2
  12. package/dist/infra/mammoth-adapter.d.ts +4 -0
  13. package/dist/infra/network-error.d.ts +9 -0
  14. package/dist/infra/sheetjs-adapter.d.ts +9 -0
  15. package/dist/infra/turndown-adapter.d.ts +4 -0
  16. package/dist/presenter/error-hints.d.ts +41 -0
  17. package/dist/presenter/output-text.d.ts +2 -0
  18. package/dist/presenter/output.d.ts +5 -2
  19. package/dist/use-cases/commands/build-command.d.ts +67 -1
  20. package/dist/use-cases/commands/command-types.d.ts +108 -3
  21. package/dist/use-cases/commands/convert-mail-attachment-to-markdown.d.ts +11 -0
  22. package/dist/use-cases/commands/convert-mail-attachment-to-pdf.d.ts +11 -0
  23. package/dist/use-cases/commands/convert-mail-to-markdown.d.ts +14 -0
  24. package/dist/use-cases/commands/docs-render.d.ts +10 -1
  25. package/dist/use-cases/commands/docs.d.ts +44 -1
  26. package/dist/use-cases/commands/docx-to-markdown.d.ts +11 -0
  27. package/dist/use-cases/commands/{download-drive-item-version-content.d.ts → download-drive-item-as-markdown.d.ts} +0 -1
  28. package/dist/use-cases/commands/download-drive-item-as-pdf.d.ts +11 -0
  29. package/dist/use-cases/commands/download-drive-item-version.d.ts +17 -0
  30. package/dist/use-cases/commands/download-onedrive-file-content.d.ts +2 -2
  31. package/dist/use-cases/commands/embedded-item-to-markdown.d.ts +59 -0
  32. package/dist/use-cases/commands/excel-error.d.ts +6 -0
  33. package/dist/use-cases/commands/extract-sharepoint-links-in-mail.d.ts +26 -0
  34. package/dist/use-cases/commands/fetch-raw-bytes.d.ts +56 -0
  35. package/dist/use-cases/commands/find-chats-with-user.d.ts +10 -0
  36. package/dist/use-cases/commands/format-zod-error.d.ts +14 -0
  37. package/dist/use-cases/commands/get-calendar-event.d.ts +1 -5
  38. package/dist/use-cases/commands/get-calendar-view.d.ts +1 -6
  39. package/dist/use-cases/commands/get-channel-files-folder.d.ts +4 -0
  40. package/dist/use-cases/commands/get-chat.d.ts +4 -0
  41. package/dist/use-cases/commands/get-current-user.d.ts +1 -3
  42. package/dist/use-cases/commands/get-drive-delta.d.ts +1 -6
  43. package/dist/use-cases/commands/get-drive-item-analytics.d.ts +9 -0
  44. package/dist/use-cases/commands/get-drive-item-created-by-user.d.ts +4 -0
  45. package/dist/use-cases/commands/get-drive-item-last-modified-by-user.d.ts +4 -0
  46. package/dist/use-cases/commands/get-drive-item-list-item.d.ts +4 -0
  47. package/dist/use-cases/commands/get-drive-item.d.ts +1 -6
  48. package/dist/use-cases/commands/get-drive-root-delta.d.ts +4 -0
  49. package/dist/use-cases/commands/get-drive-root-item.d.ts +1 -5
  50. package/dist/use-cases/commands/get-drive-special-folder.d.ts +4 -0
  51. package/dist/use-cases/commands/get-excel-range.d.ts +1 -1
  52. package/dist/use-cases/commands/get-excel-table.d.ts +1 -1
  53. package/dist/use-cases/commands/get-excel-used-range.d.ts +15 -0
  54. package/dist/use-cases/commands/get-group-calendar-view.d.ts +4 -0
  55. package/dist/use-cases/commands/get-group.d.ts +4 -0
  56. package/dist/use-cases/commands/get-mail-attachment.d.ts +4 -2
  57. package/dist/use-cases/commands/get-mail-message-mime.d.ts +8 -0
  58. package/dist/use-cases/commands/get-mail-message.d.ts +1 -5
  59. package/dist/use-cases/commands/get-mail-rule.d.ts +9 -0
  60. package/dist/use-cases/commands/get-mailbox-settings.d.ts +1 -1
  61. package/dist/use-cases/commands/get-my-calendar.d.ts +4 -0
  62. package/dist/use-cases/commands/get-my-manager.d.ts +9 -0
  63. package/dist/use-cases/commands/get-onenote-page-as-markdown.d.ts +10 -0
  64. package/dist/use-cases/commands/get-organization.d.ts +4 -0
  65. package/dist/use-cases/commands/get-shared-calendar-view.d.ts +4 -0
  66. package/dist/use-cases/commands/get-shared-mailbox-message.d.ts +4 -0
  67. package/dist/use-cases/commands/get-sharepoint-list-column.d.ts +4 -0
  68. package/dist/use-cases/commands/get-sharepoint-site-drive-by-id.d.ts +1 -6
  69. package/dist/use-cases/commands/get-sharepoint-site-list-item.d.ts +1 -7
  70. package/dist/use-cases/commands/get-sharepoint-site-list.d.ts +1 -6
  71. package/dist/use-cases/commands/get-sharepoint-site-onenote-page-content.d.ts +9 -0
  72. package/dist/use-cases/commands/get-sharepoint-site.d.ts +1 -5
  73. package/dist/use-cases/commands/get-site-analytics.d.ts +8 -0
  74. package/dist/use-cases/commands/get-specific-calendar-event.d.ts +1 -6
  75. package/dist/use-cases/commands/get-specific-calendar-view.d.ts +1 -7
  76. package/dist/use-cases/commands/get-team-channel.d.ts +3 -7
  77. package/dist/use-cases/commands/get-team-primary-channel.d.ts +4 -0
  78. package/dist/use-cases/commands/get-team.d.ts +1 -5
  79. package/dist/use-cases/commands/get-teams-chat-message.d.ts +9 -0
  80. package/dist/use-cases/commands/get-todo-task.d.ts +1 -6
  81. package/dist/use-cases/commands/get-user-manager.d.ts +10 -0
  82. package/dist/use-cases/commands/graph-scopes.d.ts +29 -0
  83. package/dist/use-cases/commands/inline-image-embedder.d.ts +20 -0
  84. package/dist/use-cases/commands/iso-datetime-schema.d.ts +21 -0
  85. package/dist/use-cases/commands/link-shape.d.ts +13 -0
  86. package/dist/use-cases/commands/list-all-onenote-sections.d.ts +1 -3
  87. package/dist/use-cases/commands/list-calendar-event-instances.d.ts +3 -9
  88. package/dist/use-cases/commands/list-calendar-events-delta.d.ts +5 -3
  89. package/dist/use-cases/commands/list-calendar-events.d.ts +1 -3
  90. package/dist/use-cases/commands/list-calendar-group-calendars.d.ts +4 -0
  91. package/dist/use-cases/commands/list-calendar-groups.d.ts +4 -0
  92. package/dist/use-cases/commands/list-calendar-view-delta.d.ts +5 -4
  93. package/dist/use-cases/commands/list-calendars.d.ts +1 -3
  94. package/dist/use-cases/commands/list-chat-members.d.ts +3 -6
  95. package/dist/use-cases/commands/list-chats.d.ts +4 -0
  96. package/dist/use-cases/commands/list-conversation-messages.d.ts +12 -0
  97. package/dist/use-cases/commands/list-drive-item-permissions.d.ts +1 -6
  98. package/dist/use-cases/commands/list-drive-item-thumbnails.d.ts +4 -0
  99. package/dist/use-cases/commands/list-drive-item-versions.d.ts +1 -6
  100. package/dist/use-cases/commands/list-drives.d.ts +1 -3
  101. package/dist/use-cases/commands/list-excel-comments.d.ts +5 -0
  102. package/dist/use-cases/commands/list-excel-defined-names.d.ts +5 -0
  103. package/dist/use-cases/commands/list-excel-table-rows.d.ts +2 -7
  104. package/dist/use-cases/commands/list-excel-tables.d.ts +2 -6
  105. package/dist/use-cases/commands/list-excel-worksheet-charts.d.ts +5 -0
  106. package/dist/use-cases/commands/list-excel-worksheet-pivot-tables.d.ts +5 -0
  107. package/dist/use-cases/commands/list-excel-worksheets.d.ts +2 -6
  108. package/dist/use-cases/commands/list-focused-inbox-overrides.d.ts +4 -0
  109. package/dist/use-cases/commands/list-folder-files.d.ts +1 -6
  110. package/dist/use-cases/commands/list-followed-drive-items.d.ts +4 -0
  111. package/dist/use-cases/commands/list-group-conversations.d.ts +4 -0
  112. package/dist/use-cases/commands/list-group-events.d.ts +4 -0
  113. package/dist/use-cases/commands/list-group-members.d.ts +4 -0
  114. package/dist/use-cases/commands/list-group-owners.d.ts +4 -0
  115. package/dist/use-cases/commands/list-group-threads.d.ts +4 -0
  116. package/dist/use-cases/commands/list-groups.d.ts +4 -0
  117. package/dist/use-cases/commands/list-incomplete-planner-tasks.d.ts +10 -3
  118. package/dist/use-cases/commands/list-incomplete-todo-tasks.d.ts +8 -2
  119. package/dist/use-cases/commands/list-mail-attachments.d.ts +8 -2
  120. package/dist/use-cases/commands/list-mail-child-folders.d.ts +1 -5
  121. package/dist/use-cases/commands/list-mail-folder-messages-delta.d.ts +4 -0
  122. package/dist/use-cases/commands/list-mail-folder-messages.d.ts +1 -5
  123. package/dist/use-cases/commands/list-mail-folders.d.ts +1 -3
  124. package/dist/use-cases/commands/list-mail-messages.d.ts +1 -3
  125. package/dist/use-cases/commands/list-mail-rules.d.ts +1 -1
  126. package/dist/use-cases/commands/list-my-direct-reports.d.ts +13 -0
  127. package/dist/use-cases/commands/list-my-memberships.d.ts +4 -0
  128. package/dist/use-cases/commands/list-my-transitive-memberships.d.ts +4 -0
  129. package/dist/use-cases/commands/list-onenote-notebook-sections.d.ts +1 -5
  130. package/dist/use-cases/commands/list-onenote-notebooks.d.ts +1 -3
  131. package/dist/use-cases/commands/list-onenote-section-pages.d.ts +1 -5
  132. package/dist/use-cases/commands/list-outlook-categories.d.ts +6 -0
  133. package/dist/use-cases/commands/list-plan-buckets.d.ts +1 -5
  134. package/dist/use-cases/commands/list-planner-plans.d.ts +1 -3
  135. package/dist/use-cases/commands/list-planner-tasks.d.ts +1 -3
  136. package/dist/use-cases/commands/list-recent-files.d.ts +4 -0
  137. package/dist/use-cases/commands/list-recently-used-insights.d.ts +4 -0
  138. package/dist/use-cases/commands/list-relevant-people.d.ts +4 -0
  139. package/dist/use-cases/commands/list-room-lists.d.ts +4 -0
  140. package/dist/use-cases/commands/list-rooms.d.ts +4 -0
  141. package/dist/use-cases/commands/list-sensitivity-labels.d.ts +4 -0
  142. package/dist/use-cases/commands/list-shared-calendar-events.d.ts +4 -0
  143. package/dist/use-cases/commands/list-shared-insights.d.ts +4 -0
  144. package/dist/use-cases/commands/list-shared-mailbox-folder-messages.d.ts +4 -0
  145. package/dist/use-cases/commands/list-shared-mailbox-messages.d.ts +4 -0
  146. package/dist/use-cases/commands/list-shared-with-me.d.ts +6 -0
  147. package/dist/use-cases/commands/list-sharepoint-list-columns.d.ts +4 -0
  148. package/dist/use-cases/commands/list-sharepoint-list-item-versions.d.ts +4 -0
  149. package/dist/use-cases/commands/list-sharepoint-site-drives.d.ts +1 -5
  150. package/dist/use-cases/commands/list-sharepoint-site-list-items.d.ts +1 -6
  151. package/dist/use-cases/commands/list-sharepoint-site-lists.d.ts +7 -2
  152. package/dist/use-cases/commands/list-sharepoint-site-onenote-notebook-sections.d.ts +5 -0
  153. package/dist/use-cases/commands/list-sharepoint-site-onenote-notebooks.d.ts +5 -0
  154. package/dist/use-cases/commands/list-sharepoint-site-onenote-section-pages.d.ts +5 -0
  155. package/dist/use-cases/commands/list-sharepoint-site-pages.d.ts +4 -0
  156. package/dist/use-cases/commands/list-site-columns.d.ts +4 -0
  157. package/dist/use-cases/commands/list-site-content-types.d.ts +4 -0
  158. package/dist/use-cases/commands/list-specific-calendar-events.d.ts +1 -5
  159. package/dist/use-cases/commands/list-team-channels.d.ts +1 -5
  160. package/dist/use-cases/commands/list-team-installed-apps.d.ts +8 -0
  161. package/dist/use-cases/commands/list-teams-chat-history.d.ts +16 -0
  162. package/dist/use-cases/commands/list-teams-chat-messages.d.ts +8 -0
  163. package/dist/use-cases/commands/list-teams-chats-with-messages.d.ts +9 -0
  164. package/dist/use-cases/commands/list-todo-linked-resources.d.ts +1 -6
  165. package/dist/use-cases/commands/list-todo-task-lists.d.ts +1 -3
  166. package/dist/use-cases/commands/list-todo-tasks-delta.d.ts +8 -0
  167. package/dist/use-cases/commands/list-todo-tasks.d.ts +8 -2
  168. package/dist/use-cases/commands/list-trending-insights.d.ts +4 -0
  169. package/dist/use-cases/commands/list-user-direct-reports.d.ts +4 -0
  170. package/dist/use-cases/commands/markdown-pipeline.d.ts +23 -0
  171. package/dist/use-cases/commands/microsoft-search-query.d.ts +8 -0
  172. package/dist/use-cases/commands/my-quick-context.d.ts +6 -0
  173. package/dist/use-cases/commands/next-page.d.ts +2 -2
  174. package/dist/use-cases/commands/odata-query.d.ts +90 -0
  175. package/dist/use-cases/commands/office-to-markdown.d.ts +6 -0
  176. package/dist/use-cases/commands/onenote-5k-limit.d.ts +3 -0
  177. package/dist/use-cases/commands/output-path.d.ts +37 -0
  178. package/dist/use-cases/commands/resolve-calendar-link.d.ts +8 -0
  179. package/dist/use-cases/commands/resolve-drive-share-link.d.ts +8 -0
  180. package/dist/use-cases/commands/resolve-mail-link.d.ts +8 -0
  181. package/dist/use-cases/commands/resolve-teams-link.d.ts +8 -0
  182. package/dist/use-cases/commands/scopes-check.d.ts +6 -0
  183. package/dist/use-cases/commands/search-mail-messages.d.ts +3 -6
  184. package/dist/use-cases/commands/search-my-documents.d.ts +1 -5
  185. package/dist/use-cases/commands/search-onedrive-files.d.ts +1 -8
  186. package/dist/use-cases/commands/search-onenote-pages.d.ts +7 -2
  187. package/dist/use-cases/commands/search-sharepoint-sites-by-name.d.ts +1 -5
  188. package/dist/use-cases/commands/sharepoint-link-extractor.d.ts +14 -0
  189. package/dist/use-cases/commands/text-passthrough.d.ts +24 -0
  190. package/dist/use-cases/commands/version-id.d.ts +19 -0
  191. package/dist/use-cases/commands/xlsx-to-markdown.d.ts +6 -0
  192. package/dist/use-cases/ports/filesystem.d.ts +8 -0
  193. package/docs/COMMANDS.md +243 -0
  194. package/docs/USAGE.md +249 -0
  195. package/docs/commands.json +5870 -789
  196. package/package.json +11 -2
  197. /package/dist/use-cases/commands/{search-sharepoint-sites.d.ts → list-mail-folders-delta.d.ts} +0 -0
@@ -3,14 +3,80 @@ import type { Result } from '../../domain/result.js';
3
3
  import type { GraphClient } from '../../infra/graph-client.js';
4
4
  type CommandSchema = z.ZodType;
5
5
  type CommandExecute = (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, import('../../infra/graph-client.js').GraphError>>;
6
- type CommandCategory = 'auth' | 'drive' | 'excel' | 'sharepoint' | 'tasks' | 'mail' | 'notes' | 'user' | 'calendar' | 'contacts' | 'chats' | 'teams' | 'meta';
6
+ type CommandCategory = 'drive' | 'excel' | 'sharepoint' | 'tasks' | 'mail' | 'notes' | 'user' | 'calendar' | 'chats' | 'teams' | 'meta' | 'lifecycle';
7
7
  type CommandHttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
8
+ type CommandOptionAlias = {
9
+ readonly name: string;
10
+ readonly key: string;
11
+ };
12
+ /**
13
+ * Structured type-hint for a CLI flag value. Surfaces in `help-json` so an
14
+ * LLM can avoid the trial-and-error of "is this an ID or a name?" prose
15
+ * reading. Optional — populate only where the hint is non-obvious from the
16
+ * flag name itself.
17
+ */
18
+ type ArgumentHint = {
19
+ readonly kind: 'idOrName';
20
+ } | {
21
+ readonly kind: 'magicValue';
22
+ readonly values: ReadonlyArray<string>;
23
+ } | {
24
+ readonly kind: 'a1Address';
25
+ } | {
26
+ readonly kind: 'iso8601';
27
+ } | {
28
+ readonly kind: 'graphSubpath';
29
+ };
8
30
  type CommandOptionMeta = {
9
31
  readonly name: string;
10
32
  readonly key: string;
11
33
  readonly description: string;
12
- readonly required: true;
34
+ /**
35
+ * `true` for required flags (the historical default; commander rejects the
36
+ * invocation if the flag is missing). `false` for optional flags such as the
37
+ * OData passthrough query parameters (`--top`, `--filter`, …) which
38
+ * commands accept but do not demand.
39
+ */
40
+ readonly required: boolean;
41
+ /**
42
+ * Optional secondary spellings of the same flag. Both the canonical
43
+ * `name` and every alias name are accepted on the command line; values
44
+ * passed under an alias are normalized to the canonical `key` before
45
+ * the schema runs. The canonical name is what `--help` shows first.
46
+ */
47
+ readonly aliases?: ReadonlyArray<CommandOptionAlias>;
48
+ /**
49
+ * Structured value-type hint for LLM consumers. Optional.
50
+ */
51
+ readonly argumentHint?: ArgumentHint;
52
+ };
53
+ /**
54
+ * A positional argument (i.e. NOT a `--flag`). Used today only for the
55
+ * `docs` lifecycle command (`ask-marcel docs <command>`) but kept as its
56
+ * own field so the manifest never claims a positional is a flag. An LLM
57
+ * consumer reading `help-json` can branch on the presence of
58
+ * `positionalArguments` to know to skip the `--` prefix.
59
+ */
60
+ type CommandPositionalArgumentMeta = {
61
+ readonly name: string;
62
+ readonly required: boolean;
63
+ readonly description: string;
13
64
  };
65
+ /**
66
+ * How a paginated command produces subsequent pages. Optional — populate
67
+ * for any command that has `pagination: true`. Lets an LLM tell which
68
+ * cursor field to feed back to `next-page` (or whether `next-page` is even
69
+ * applicable, vs `deltaLink`, vs the header-translation case).
70
+ */
71
+ type PaginationStrategy =
72
+ /** Standard: `?$top=N&$skip=K` + `@odata.nextLink` cursor. */
73
+ 'nextLink'
74
+ /** `?$top=N` + `nextLink` (Graph rejects `$skip` on this endpoint). */
75
+ | 'nextLinkNoSkip'
76
+ /** Delta endpoints — `nextLink` while paging, `deltaLink` on final page. */
77
+ | 'deltaLink'
78
+ /** `--top` translated to `Prefer: odata.maxpagesize` header; `$top` rejected as query. */
79
+ | 'preferMaxPageSize';
14
80
  type CommandMeta = {
15
81
  readonly summary: string;
16
82
  readonly category: CommandCategory;
@@ -18,13 +84,52 @@ type CommandMeta = {
18
84
  readonly graphPathTemplate: string;
19
85
  readonly graphDocsUrl: string;
20
86
  readonly options: ReadonlyArray<CommandOptionMeta>;
87
+ readonly positionalArguments?: ReadonlyArray<CommandPositionalArgumentMeta>;
21
88
  readonly example: string;
22
89
  readonly responseShape?: string;
23
90
  readonly bodyTemplate?: string;
91
+ readonly pagination?: true;
92
+ readonly paginationStrategy?: PaginationStrategy;
93
+ /**
94
+ * Graph permission scopes the endpoint requires. The basic Teams web-client
95
+ * token grants ~30 scopes (run `ask-marcel scopes-check` to see). Commands
96
+ * with unmet scopes return `403 Forbidden: Missing scope` at the wire. Use
97
+ * this for pre-flight checks rather than failing on-the-wire. Optional —
98
+ * populated only on commands where the audit confirmed a scope-failure
99
+ * path; absent means "should work with the basic Teams token".
100
+ */
101
+ readonly scopesRequired?: ReadonlyArray<string>;
102
+ /**
103
+ * `true` if the command needs the M365ChatClient elevated token (captured
104
+ * at login from `m365.cloud.microsoft`, ODSP allow-list). Only 3 commands
105
+ * today — the historical-version downloads. An LLM should check this
106
+ * field before invoking; if the elevated capture failed at login, these
107
+ * commands will time out.
108
+ */
109
+ readonly needsElevatedToken?: true;
110
+ /**
111
+ * `true` if the command returns inlined bytes (`{contentType, size, base64}`
112
+ * or `{contentType, size, text}`) and is therefore a valid target for the
113
+ * global `--output-path` flag. Used by the CLI composition to derive the
114
+ * rejection-message whitelist from the manifest rather than hand-keeping it
115
+ * as a string literal. Audit round-8 Wave E2.
116
+ */
117
+ readonly producesBytes?: true;
118
+ /**
119
+ * Stability tier of the command. Omitted from manifest entries when the
120
+ * command is `'stable'` (the implicit default), surfaced only on
121
+ * `'experimental'` commands so an LLM can prefer stable siblings when they
122
+ * exist. `'experimental'` today means the command rides a Microsoft-internal
123
+ * substrate (chatsvcagg / IC3) that is not in the public Graph API and can
124
+ * break on a Teams web-client update — the docstring "Best-effort, may break
125
+ * on Microsoft client updates" warnings now have a structured pair.
126
+ * Audit Hervé-session §6.
127
+ */
128
+ readonly stability?: 'experimental';
24
129
  };
25
130
  type Command = {
26
131
  readonly schema: CommandSchema;
27
132
  readonly execute: CommandExecute;
28
133
  readonly meta: CommandMeta;
29
134
  };
30
- export type { Command, CommandCategory, CommandExecute, CommandHttpMethod, CommandMeta, CommandOptionMeta, CommandSchema };
135
+ export type { ArgumentHint, Command, CommandCategory, CommandExecute, CommandHttpMethod, CommandMeta, CommandOptionAlias, CommandOptionMeta, CommandPositionalArgumentMeta, CommandSchema, PaginationStrategy, };
@@ -0,0 +1,11 @@
1
+ import { z } from 'zod';
2
+ import type { Result } from '../../domain/result.js';
3
+ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
4
+ import type { CommandMeta } from './command-types.js';
5
+ declare const schema: z.ZodObject<{
6
+ messageId: z.ZodString;
7
+ attachmentId: z.ZodString;
8
+ }, z.core.$strip>;
9
+ declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
10
+ declare const meta: CommandMeta;
11
+ export { execute, meta, schema };
@@ -0,0 +1,11 @@
1
+ import { z } from 'zod';
2
+ import type { Result } from '../../domain/result.js';
3
+ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
4
+ import type { CommandMeta } from './command-types.js';
5
+ declare const schema: z.ZodObject<{
6
+ messageId: z.ZodString;
7
+ attachmentId: z.ZodString;
8
+ }, z.core.$strip>;
9
+ declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
10
+ declare const meta: CommandMeta;
11
+ export { execute, meta, schema };
@@ -0,0 +1,14 @@
1
+ import { z } from 'zod';
2
+ import type { Result } from '../../domain/result.js';
3
+ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
4
+ import type { CommandMeta } from './command-types.js';
5
+ declare const schema: z.ZodObject<{
6
+ messageId: z.ZodString;
7
+ inlineImages: z.ZodOptional<z.ZodEnum<{
8
+ true: "true";
9
+ false: "false";
10
+ }>>;
11
+ }, z.core.$strip>;
12
+ declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
13
+ declare const meta: CommandMeta;
14
+ export { execute, meta, schema };
@@ -1,4 +1,4 @@
1
- import type { CommandCategory, CommandMeta } from './command-types.js';
1
+ import type { CommandCategory, CommandMeta, PaginationStrategy } from './command-types.js';
2
2
  export type CommandManifestEntry = {
3
3
  readonly name: string;
4
4
  readonly summary: string;
@@ -7,10 +7,19 @@ export type CommandManifestEntry = {
7
7
  readonly graphPathTemplate: string;
8
8
  readonly graphDocsUrl: string;
9
9
  readonly options: CommandMeta['options'];
10
+ readonly positionalArguments?: CommandMeta['positionalArguments'];
10
11
  readonly example: string;
11
12
  readonly responseShape?: string;
12
13
  readonly bodyTemplate?: string;
14
+ readonly pagination?: true;
15
+ readonly paginationStrategy?: CommandMeta['paginationStrategy'];
16
+ readonly scopesRequired?: CommandMeta['scopesRequired'];
17
+ readonly needsElevatedToken?: CommandMeta['needsElevatedToken'];
18
+ readonly producesBytes?: CommandMeta['producesBytes'];
19
+ readonly stability?: CommandMeta['stability'];
13
20
  };
21
+ export declare const paginationHintFor: (strategy: PaginationStrategy | undefined) => string;
22
+ 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.";
14
23
  export type CommandManifest = {
15
24
  readonly package: string;
16
25
  readonly version: string;
@@ -1,10 +1,53 @@
1
1
  import type { Result } from '../../domain/result.js';
2
- import type { Command } from './command-types.js';
2
+ import type { CommandCategory, Command, CommandMeta } from './command-types.js';
3
3
  import type { CommandManifest } from './docs-render.js';
4
4
  export type DocsError = {
5
5
  type: 'unknown_command';
6
6
  readonly name: string;
7
7
  readonly available: ReadonlyArray<string>;
8
8
  };
9
+ /**
10
+ * Terse manifest entry — only the fields an LLM needs to *discover* a command
11
+ * (i.e. "does this CLI do X?"). Drops `options`, `example`, `graphPathTemplate`,
12
+ * `graphDocsUrl`, `responseShape`, `bodyTemplate`, `paginationStrategy`,
13
+ * `scopesRequired` — everything the LLM only needs once it's already decided
14
+ * to invoke. `stability` is kept (it's a discovery-time concern: LLMs prefer
15
+ * stable siblings when they exist, so they need to see the tag at discovery
16
+ * time, not after a second full-manifest fetch). Audit Hervé-session §B/§6.
17
+ */
18
+ export type TerseManifestEntry = {
19
+ readonly name: string;
20
+ readonly summary: string;
21
+ readonly category: CommandCategory;
22
+ readonly stability?: CommandMeta['stability'];
23
+ };
24
+ export type TerseManifest = {
25
+ readonly package: string;
26
+ readonly version: string;
27
+ readonly generatedAt: string;
28
+ readonly commands: ReadonlyArray<TerseManifestEntry>;
29
+ };
30
+ export type ManifestFilterError = {
31
+ readonly type: 'unknown_category';
32
+ readonly category: string;
33
+ readonly available: ReadonlyArray<string>;
34
+ };
9
35
  export declare const buildManifest: (registry: Readonly<Record<string, Command>>, packageName: string, version: string, now?: () => Date) => CommandManifest;
36
+ /**
37
+ * Terse manifest — `{ name, summary, category }` per command. Roughly 95%
38
+ * smaller than the full manifest (no options/example/Graph endpoint per entry).
39
+ * Use `help-json --terse` to surface this to an LLM as the discovery view.
40
+ */
41
+ export declare const buildTerseManifest: (registry: Readonly<Record<string, Command>>, packageName: string, version: string, now?: () => Date) => TerseManifest;
42
+ /**
43
+ * Filter a `CommandManifest` (or terse variant) down to a single category.
44
+ * Returns `err({ type: 'unknown_category', ... })` if the requested category
45
+ * isn't a known one — the CLI surfaces this through the standard error
46
+ * envelope rather than silently returning an empty list.
47
+ */
48
+ export declare const filterManifestByCategory: <M extends {
49
+ readonly commands: ReadonlyArray<{
50
+ readonly category: CommandCategory;
51
+ }>;
52
+ }>(manifest: M, category: string) => Result<M, ManifestFilterError>;
10
53
  export declare const renderSingleCommand: (registry: Readonly<Record<string, Command>>, name: string) => Result<string, DocsError>;
@@ -0,0 +1,11 @@
1
+ import type { Result } from '../../domain/result.js';
2
+ import type { GraphError } from '../../infra/graph-client.js';
3
+ type MarkdownEnvelope = {
4
+ readonly contentType: 'text/markdown';
5
+ readonly size: number;
6
+ readonly text: string;
7
+ };
8
+ declare const promoteFirstRowToThead: (html: string) => string;
9
+ declare const docxToMarkdown: (bytes: Uint8Array) => Promise<Result<MarkdownEnvelope, GraphError>>;
10
+ export { docxToMarkdown, promoteFirstRowToThead };
11
+ export type { MarkdownEnvelope };
@@ -5,7 +5,6 @@ import type { CommandMeta } from './command-types.js';
5
5
  declare const schema: z.ZodObject<{
6
6
  driveId: z.ZodString;
7
7
  itemId: z.ZodString;
8
- versionId: z.ZodString;
9
8
  }, z.core.$strip>;
10
9
  declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
11
10
  declare const meta: CommandMeta;
@@ -0,0 +1,11 @@
1
+ import { z } from 'zod';
2
+ import type { Result } from '../../domain/result.js';
3
+ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
4
+ import type { CommandMeta } from './command-types.js';
5
+ declare const schema: z.ZodObject<{
6
+ driveId: z.ZodString;
7
+ itemId: z.ZodString;
8
+ }, z.core.$strip>;
9
+ declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
10
+ declare const meta: CommandMeta;
11
+ export { execute, meta, schema };
@@ -0,0 +1,17 @@
1
+ import { z } from 'zod';
2
+ import type { Result } from '../../domain/result.js';
3
+ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
4
+ import type { CommandMeta } from './command-types.js';
5
+ declare const schema: z.ZodObject<{
6
+ driveId: z.ZodString;
7
+ itemId: z.ZodString;
8
+ versionId: z.ZodString;
9
+ format: z.ZodOptional<z.ZodEnum<{
10
+ markdown: "markdown";
11
+ pdf: "pdf";
12
+ original: "original";
13
+ }>>;
14
+ }, z.core.$strip>;
15
+ declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
16
+ declare const meta: CommandMeta;
17
+ export { execute, meta, schema };
@@ -1,11 +1,11 @@
1
1
  import { z } from 'zod';
2
2
  import type { Result } from '../../domain/result.js';
3
- import type { GraphClient } from '../../infra/graph-client.js';
3
+ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
4
4
  import type { CommandMeta } from './command-types.js';
5
5
  declare const schema: z.ZodObject<{
6
6
  driveId: z.ZodString;
7
7
  itemId: z.ZodString;
8
8
  }, z.core.$strip>;
9
- declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, import("../../infra/graph-client.js").GraphError>>;
9
+ declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
10
10
  declare const meta: CommandMeta;
11
11
  export { execute, meta, schema };
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Render an itemAttachment's inner resource (a `microsoft.graph.message`,
3
+ * `event`, or `contact`) directly to markdown — no RTF round-trip, no
4
+ * Graph conversion call.
5
+ *
6
+ * Each renderer emits a small header block (`**Subject:** …`, etc.) and
7
+ * appends the body run through htmlToMarkdown when the inner resource
8
+ * has one. Callers (the convert-mail-attachment-to-markdown command)
9
+ * choose the right renderer by branching on `item['@odata.type']`.
10
+ */
11
+ type EmailAddress = {
12
+ readonly name?: string;
13
+ readonly address?: string;
14
+ };
15
+ type Recipient = {
16
+ readonly emailAddress?: EmailAddress;
17
+ };
18
+ type Body = {
19
+ readonly contentType?: string;
20
+ readonly content?: string;
21
+ };
22
+ type EmbeddedMessage = {
23
+ readonly subject?: string;
24
+ readonly from?: Recipient;
25
+ readonly toRecipients?: ReadonlyArray<Recipient>;
26
+ readonly sentDateTime?: string;
27
+ readonly body?: Body;
28
+ };
29
+ declare const embeddedMessageToMarkdown: (m: EmbeddedMessage) => string;
30
+ type EventDateTime = {
31
+ readonly dateTime?: string;
32
+ readonly timeZone?: string;
33
+ };
34
+ type Location = {
35
+ readonly displayName?: string;
36
+ };
37
+ type EmbeddedEvent = {
38
+ readonly subject?: string;
39
+ readonly start?: EventDateTime;
40
+ readonly end?: EventDateTime;
41
+ readonly location?: Location;
42
+ readonly organizer?: Recipient;
43
+ readonly attendees?: ReadonlyArray<Recipient>;
44
+ readonly body?: Body;
45
+ };
46
+ declare const embeddedEventToMarkdown: (e: EmbeddedEvent) => string;
47
+ type EmbeddedContact = {
48
+ readonly displayName?: string;
49
+ readonly emailAddresses?: ReadonlyArray<{
50
+ address?: string;
51
+ }>;
52
+ readonly businessPhones?: ReadonlyArray<string>;
53
+ readonly mobilePhone?: string;
54
+ readonly companyName?: string;
55
+ readonly jobTitle?: string;
56
+ };
57
+ declare const embeddedContactToMarkdown: (c: EmbeddedContact) => string;
58
+ export { embeddedContactToMarkdown, embeddedEventToMarkdown, embeddedMessageToMarkdown };
59
+ export type { EmbeddedContact, EmbeddedEvent, EmbeddedMessage };
@@ -0,0 +1,6 @@
1
+ import type { Result } from '../../domain/result.js';
2
+ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
3
+ declare const mapWacError: (e: GraphError) => GraphError;
4
+ type ExecuteFn = (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
5
+ declare const wrapExcelExecute: (inner: ExecuteFn) => ExecuteFn;
6
+ export { mapWacError, wrapExcelExecute };
@@ -0,0 +1,26 @@
1
+ import { z } from 'zod';
2
+ import type { Result } from '../../domain/result.js';
3
+ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
4
+ import type { CommandMeta } from './command-types.js';
5
+ type ResolvedLink = {
6
+ readonly url: string;
7
+ readonly driveId?: string;
8
+ readonly itemId?: string;
9
+ readonly name?: string;
10
+ readonly webUrl?: string;
11
+ readonly error?: string;
12
+ };
13
+ type LinkExtractionSummary = {
14
+ readonly messageId: string;
15
+ readonly subject?: string;
16
+ readonly links: ReadonlyArray<ResolvedLink>;
17
+ readonly truncated: boolean;
18
+ readonly skippedCount: number;
19
+ };
20
+ declare const schema: z.ZodObject<{
21
+ messageId: z.ZodString;
22
+ }, z.core.$strip>;
23
+ declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<LinkExtractionSummary, GraphError>>;
24
+ declare const meta: CommandMeta;
25
+ export { execute, meta, schema };
26
+ export type { LinkExtractionSummary, ResolvedLink };
@@ -0,0 +1,56 @@
1
+ import type { Result } from '../../domain/result.js';
2
+ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
3
+ /**
4
+ * Helpers that consolidate the "Graph hands you a 302, follow the CDN
5
+ * redirect, return the bytes" dance used by every command that needs
6
+ * raw file content.
7
+ *
8
+ * Real Graph responses for `/drives/{id}/items/{id}/content` (and the
9
+ * `?format=pdf` / `?format=html` variants) are 302 redirects to a CDN URL.
10
+ * `getBinary` captures the redirect and returns
11
+ * `{ '@microsoft.graph.downloadUrl': '...' }` — NOT inline bytes. To get
12
+ * the bytes we have to follow the URL via `fetchUrl`, which is host-allow-
13
+ * listed for SharePoint / ODSP / Microsoft media-transform domains.
14
+ *
15
+ * Two shapes for the return value depending on what the caller needs:
16
+ * - `fetchRawBytes(graph, path, opts)` → `Uint8Array` for local
17
+ * conversion (mammoth / sheetjs / turndown).
18
+ * - `inlineBinary(graph, path, opts)` → `{ contentType, size, base64 }`
19
+ * for "stream the bytes back through the JSON envelope" workflows
20
+ * (PDF conversion, image attachments, anything the LLM consumer
21
+ * either pipes to disk or saves via --output-path).
22
+ *
23
+ * The historical-version commands pass `elevated: true` so that the
24
+ * initial Graph call is signed with an M365ChatClient token (on the
25
+ * ODSP `logicalPermissions` allow-list); without that, Graph's 302
26
+ * redirects to a streamContent URL whose embedded tempauth is signed
27
+ * by Teams web client identity and rejected by SharePoint with 403.
28
+ */
29
+ export type FetchOptions = {
30
+ readonly elevated?: boolean;
31
+ };
32
+ export type InlineBinary = {
33
+ readonly contentType: string;
34
+ readonly size: number;
35
+ readonly base64: string;
36
+ };
37
+ export declare const fetchRawBytes: (graph: GraphClient, contentPath: string, opts?: FetchOptions) => Promise<Result<Uint8Array, GraphError>>;
38
+ export declare const inlineBinary: (graph: GraphClient, contentPath: string, opts?: FetchOptions) => Promise<Result<InlineBinary, GraphError>>;
39
+ /**
40
+ * Detect Graph's silent-raw-bytes fallback on `?format=pdf` requests.
41
+ *
42
+ * When `format=pdf` succeeds, the response contentType is `application/pdf`.
43
+ * For some inputs (notably historical-version pptx on certain tenants, or
44
+ * reference-attachment edge cases) Graph silently falls back to returning
45
+ * the raw source bytes — same envelope shape, but contentType is the
46
+ * source MIME (or `application/octet-stream`). The audit (round-5 #2)
47
+ * caught this happening on `download-drive-item-version --format pdf` for v79
48
+ * of a pptx: the response said `contentType: "application/octet-stream"`
49
+ * with the exact source byte size, and an LLM that saved it as `.pdf`
50
+ * would have had a corrupt file.
51
+ *
52
+ * Tag the result with `passthrough: true` and a sharp note so the LLM
53
+ * knows the conversion didn't run and saves the bytes with the source
54
+ * extension instead of `.pdf`.
55
+ */
56
+ export declare const tagPdfPassthrough: (result: Result<InlineBinary, GraphError>, sourceLabel: string) => Result<unknown, GraphError>;
@@ -0,0 +1,10 @@
1
+ import { z } from 'zod';
2
+ import type { Command, CommandMeta } from './command-types.js';
3
+ declare const schema: z.ZodObject<{
4
+ name: z.ZodString;
5
+ maxPages: z.ZodOptional<z.ZodString>;
6
+ pageSize: z.ZodOptional<z.ZodString>;
7
+ }, z.core.$strip>;
8
+ declare const execute: Command['execute'];
9
+ declare const meta: CommandMeta;
10
+ export { execute, meta, schema };
@@ -0,0 +1,14 @@
1
+ import type { z } from 'zod';
2
+ /**
3
+ * Render a Zod validation error as a single human-readable line keyed off the
4
+ * CLI flag name. The audit's gripe with the previous formatter
5
+ * (`messageRuleId: Too small: expected string to have >=1 characters`) was
6
+ * that an LLM piping the JSON envelope through jq sees Zod jargon plus the
7
+ * camelCase schema key — neither matches what the user typed on the command
8
+ * line. This formatter prepends `--<kebab-case-flag>` and translates the two
9
+ * common Zod codes to plain English: missing values become `is missing`,
10
+ * empty strings become `is empty`. Multi-issue failures join with `; ` to
11
+ * stay on one line.
12
+ */
13
+ declare const formatZodError: (error: z.ZodError) => string;
14
+ export { formatZodError };
@@ -1,8 +1,4 @@
1
- import { z } from 'zod';
2
1
  import type { CommandMeta } from './command-types.js';
3
- declare const schema: z.ZodObject<{
4
- eventId: z.ZodString;
5
- }, z.core.$strip>;
6
- declare const execute: import("./command-types.js").CommandExecute;
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
7
3
  declare const meta: CommandMeta;
8
4
  export { execute, meta, schema };
@@ -1,9 +1,4 @@
1
- import { z } from 'zod';
2
1
  import type { CommandMeta } from './command-types.js';
3
- declare const schema: z.ZodObject<{
4
- startDateTime: z.ZodString;
5
- endDateTime: z.ZodString;
6
- }, z.core.$strip>;
7
- declare const execute: import("./command-types.js").CommandExecute;
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
8
3
  declare const meta: CommandMeta;
9
4
  export { execute, meta, schema };
@@ -0,0 +1,4 @@
1
+ import type { CommandMeta } from './command-types.js';
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
3
+ declare const meta: CommandMeta;
4
+ export { execute, meta, schema };
@@ -0,0 +1,4 @@
1
+ import type { CommandMeta } from './command-types.js';
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
3
+ declare const meta: CommandMeta;
4
+ export { execute, meta, schema };
@@ -1,6 +1,4 @@
1
- import { z } from 'zod';
2
1
  import type { CommandMeta } from './command-types.js';
3
- declare const schema: z.ZodObject<{}, z.core.$strict>;
4
- declare const execute: import("./command-types.js").CommandExecute;
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
5
3
  declare const meta: CommandMeta;
6
4
  export { execute, meta, schema };
@@ -1,9 +1,4 @@
1
- import { z } from 'zod';
2
1
  import type { CommandMeta } from './command-types.js';
3
- declare const schema: z.ZodObject<{
4
- driveId: z.ZodString;
5
- itemId: z.ZodString;
6
- }, z.core.$strip>;
7
- declare const execute: import("./command-types.js").CommandExecute;
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
8
3
  declare const meta: CommandMeta;
9
4
  export { execute, meta, schema };
@@ -0,0 +1,9 @@
1
+ import { z } from 'zod';
2
+ import type { CommandMeta } from './command-types.js';
3
+ declare const schema: z.ZodObject<{
4
+ driveId: z.ZodString;
5
+ itemId: z.ZodString;
6
+ }, z.core.$strip>;
7
+ declare const execute: import("./command-types.js").CommandExecute;
8
+ declare const meta: CommandMeta;
9
+ export { execute, meta, schema };
@@ -0,0 +1,4 @@
1
+ import type { CommandMeta } from './command-types.js';
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
3
+ declare const meta: CommandMeta;
4
+ export { execute, meta, schema };
@@ -0,0 +1,4 @@
1
+ import type { CommandMeta } from './command-types.js';
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
3
+ declare const meta: CommandMeta;
4
+ export { execute, meta, schema };
@@ -0,0 +1,4 @@
1
+ import type { CommandMeta } from './command-types.js';
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
3
+ declare const meta: CommandMeta;
4
+ export { execute, meta, schema };
@@ -1,9 +1,4 @@
1
- import { z } from 'zod';
2
1
  import type { CommandMeta } from './command-types.js';
3
- declare const schema: z.ZodObject<{
4
- driveId: z.ZodString;
5
- itemId: z.ZodString;
6
- }, z.core.$strip>;
7
- declare const execute: import("./command-types.js").CommandExecute;
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
8
3
  declare const meta: CommandMeta;
9
4
  export { execute, meta, schema };
@@ -0,0 +1,4 @@
1
+ import type { CommandMeta } from './command-types.js';
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
3
+ declare const meta: CommandMeta;
4
+ export { execute, meta, schema };
@@ -1,8 +1,4 @@
1
- import { z } from 'zod';
2
1
  import type { CommandMeta } from './command-types.js';
3
- declare const schema: z.ZodObject<{
4
- driveId: z.ZodString;
5
- }, z.core.$strip>;
6
- declare const execute: import("./command-types.js").CommandExecute;
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
7
3
  declare const meta: CommandMeta;
8
4
  export { execute, meta, schema };
@@ -0,0 +1,4 @@
1
+ import type { CommandMeta } from './command-types.js';
2
+ declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
3
+ declare const meta: CommandMeta;
4
+ export { execute, meta, schema };
@@ -6,6 +6,6 @@ declare const schema: z.ZodObject<{
6
6
  worksheetId: z.ZodString;
7
7
  address: z.ZodString;
8
8
  }, z.core.$strip>;
9
- declare const execute: import("./command-types.js").CommandExecute;
9
+ declare const execute: (graph: import("../../index.js").GraphClient, params: Record<string, string>) => Promise<import("../../index.js").Result<unknown, import("../../index.js").GraphError>>;
10
10
  declare const meta: CommandMeta;
11
11
  export { execute, meta, schema };