@khanglvm/outline-cli 0.1.8 → 0.2.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.
- package/CHANGELOG.md +5 -0
- package/README.md +22 -1
- package/package.json +1 -1
- package/src/agent-skills.js +5 -2
- package/src/entry-integrity-manifest.generated.js +5 -5
- package/src/tool-arg-schemas.js +24 -2
- package/src/tools.extended.js +420 -8
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.2.0 - 2026-06-23
|
|
4
|
+
|
|
5
|
+
- Changes since `v0.1.8`.
|
|
6
|
+
- feat(comments): ergonomic commenting with @-mentions — `comments.create`/`comments.post` accept plain/markdown `text` and build the Outline ProseMirror `data` doc, resolve `mentions` (names/emails/userIds, first-name + email matching) into mention nodes, enforce the 1000-character text limit pre-flight, and support `parentCommentId` replies; `comments.list` documents `includeReplies`/`parentCommentId` for reading replies.
|
|
7
|
+
|
|
3
8
|
## 0.1.8 - 2026-06-11
|
|
4
9
|
|
|
5
10
|
- Changes since `v0.1.7`.
|
package/README.md
CHANGED
|
@@ -237,11 +237,32 @@ outline-cli invoke comments.list \
|
|
|
237
237
|
--args '{"query":"incident runbook","includeReplies":true,"limit":20,"view":"summary"}'
|
|
238
238
|
```
|
|
239
239
|
|
|
240
|
-
Create a comment directly from a remembered document title
|
|
240
|
+
Create a comment directly from a remembered document title. Pass plain/markdown
|
|
241
|
+
`text` (the ProseMirror `data` doc is built for you) and an optional `mentions`
|
|
242
|
+
list of names, emails, or userIds. Names match on **first name**, so Jira-order
|
|
243
|
+
`"Tran Le Quan"` resolves to Outline's `"Quan, Tran Le"`. The comment text is
|
|
244
|
+
capped at 1000 characters (checked pre-flight). `comments.post` is an alias.
|
|
241
245
|
|
|
242
246
|
```bash
|
|
247
|
+
# simple comment
|
|
243
248
|
outline-cli invoke comments.create \
|
|
244
249
|
--args '{"query":"incident runbook","text":"Looks good.","performAction":true}'
|
|
250
|
+
|
|
251
|
+
# comment with @-mentions (resolved to user IDs and inserted at the start)
|
|
252
|
+
outline-cli invoke comments.create \
|
|
253
|
+
--args '{"query":"incident runbook","text":"Please review the rollback steps.","mentions":["Tran Le Quan","alice@example.com"],"performAction":true}'
|
|
254
|
+
|
|
255
|
+
# reply to an existing comment
|
|
256
|
+
outline-cli invoke comments.post \
|
|
257
|
+
--args '{"documentId":"<doc-id>","parentCommentId":"<comment-id>","text":"Confirmed.","performAction":true}'
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
Read a comment's replies later with `comments.list` (set `includeReplies:true`,
|
|
261
|
+
or pass `parentCommentId` to fetch one thread's replies):
|
|
262
|
+
|
|
263
|
+
```bash
|
|
264
|
+
outline-cli invoke comments.list \
|
|
265
|
+
--args '{"query":"incident runbook","includeReplies":true,"view":"summary"}'
|
|
245
266
|
```
|
|
246
267
|
|
|
247
268
|
List share links directly from a remembered document title:
|
package/package.json
CHANGED
package/src/agent-skills.js
CHANGED
|
@@ -737,8 +737,10 @@ const AI_SKILLS = [
|
|
|
737
737
|
objective: "Build deterministic review queues and close loops with comment evidence.",
|
|
738
738
|
featureUpdates: [
|
|
739
739
|
"comments.review_queue wrapper added for scoped editorial queues.",
|
|
740
|
-
"comments.list can resolve remembered document refs for direct thread hydration.",
|
|
741
|
-
"comments.create
|
|
740
|
+
"comments.list can resolve remembered document refs for direct thread hydration (includeReplies=true to nest replies).",
|
|
741
|
+
"comments.create / comments.post accept plain text and build the ProseMirror data doc for you.",
|
|
742
|
+
"comments.create / comments.post accept mentions (names/emails/userIds) and auto-insert @-mention nodes; names match on first name.",
|
|
743
|
+
"comments.create / comments.post enforce the 1000-character comment limit pre-flight and accept parentCommentId for replies.",
|
|
742
744
|
"Thread/reply and anchor metadata can be included for full review context.",
|
|
743
745
|
],
|
|
744
746
|
sequence: [
|
|
@@ -772,6 +774,7 @@ const AI_SKILLS = [
|
|
|
772
774
|
"Scope review_queue to explicit documentIds whenever possible.",
|
|
773
775
|
"Pass query/refs/url/urlId directly to comments.list when drilling into one remembered document.",
|
|
774
776
|
"Pass query/refs/url/urlId directly to comments.create when adding an approved comment to a remembered document.",
|
|
777
|
+
"Use comments.create/comments.post with plain text + mentions instead of hand-building ProseMirror data; pass an email or userId when a first name is ambiguous.",
|
|
775
778
|
"Use limitPerDocument to control queue growth and rerun with cursor-like cadence.",
|
|
776
779
|
],
|
|
777
780
|
safetyChecks: [
|
|
@@ -3,8 +3,8 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
|
|
|
3
3
|
version: 1,
|
|
4
4
|
algorithm: "sha256",
|
|
5
5
|
signatureAlgorithm: "sha256-salted-manifest-v1",
|
|
6
|
-
signature: "
|
|
7
|
-
generatedAt: "2026-06-
|
|
6
|
+
signature: "40638ba4d3f763d584f68234f135e58af065f6cb019257ea0a051dc10010e39a",
|
|
7
|
+
generatedAt: "2026-06-23T00:27:13.815Z",
|
|
8
8
|
files: [
|
|
9
9
|
{
|
|
10
10
|
"path": "src/action-gate.js",
|
|
@@ -12,7 +12,7 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
|
|
|
12
12
|
},
|
|
13
13
|
{
|
|
14
14
|
"path": "src/agent-skills.js",
|
|
15
|
-
"sha256": "
|
|
15
|
+
"sha256": "7da906f5fc1c819311bfdf50719ade949586c9a13cb51c0142fff360eed4ac7f"
|
|
16
16
|
},
|
|
17
17
|
{
|
|
18
18
|
"path": "src/cli.js",
|
|
@@ -52,11 +52,11 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
|
|
|
52
52
|
},
|
|
53
53
|
{
|
|
54
54
|
"path": "src/tool-arg-schemas.js",
|
|
55
|
-
"sha256": "
|
|
55
|
+
"sha256": "ebc813dd48d5aeb44c655914d504f5ee1ec1ef8205bdec7c5f9adebb3337bd0d"
|
|
56
56
|
},
|
|
57
57
|
{
|
|
58
58
|
"path": "src/tools.extended.js",
|
|
59
|
-
"sha256": "
|
|
59
|
+
"sha256": "acbd8f5b297c4d4c08e913a710230879e63a230886592823b716bdb5b5cca52d"
|
|
60
60
|
},
|
|
61
61
|
{
|
|
62
62
|
"path": "src/tools.js",
|
package/src/tool-arg-schemas.js
CHANGED
|
@@ -2954,6 +2954,7 @@ export const TOOL_ARG_SCHEMAS = {
|
|
|
2954
2954
|
properties: {
|
|
2955
2955
|
...DOCUMENT_TARGET_RESOLVE_PROPERTIES,
|
|
2956
2956
|
text: { type: "string" },
|
|
2957
|
+
mentions: { type: "string[]" },
|
|
2957
2958
|
data: { type: "object" },
|
|
2958
2959
|
parentCommentId: { type: "string" },
|
|
2959
2960
|
includePolicies: { type: "boolean" },
|
|
@@ -2963,8 +2964,29 @@ export const TOOL_ARG_SCHEMAS = {
|
|
|
2963
2964
|
},
|
|
2964
2965
|
custom(args, issues) {
|
|
2965
2966
|
validateRequiredDocumentResolveArgs(args, issues);
|
|
2966
|
-
|
|
2967
|
-
|
|
2967
|
+
const hasMentions = Array.isArray(args.mentions) && args.mentions.length > 0;
|
|
2968
|
+
if (!args.text && !args.data && !hasMentions) {
|
|
2969
|
+
issues.push({ path: "args.text", message: "or args.data or args.mentions is required" });
|
|
2970
|
+
}
|
|
2971
|
+
},
|
|
2972
|
+
},
|
|
2973
|
+
"comments.post": {
|
|
2974
|
+
properties: {
|
|
2975
|
+
...DOCUMENT_TARGET_RESOLVE_PROPERTIES,
|
|
2976
|
+
text: { type: "string" },
|
|
2977
|
+
mentions: { type: "string[]" },
|
|
2978
|
+
data: { type: "object" },
|
|
2979
|
+
parentCommentId: { type: "string" },
|
|
2980
|
+
includePolicies: { type: "boolean" },
|
|
2981
|
+
view: { type: "string", enum: ["summary", "full"] },
|
|
2982
|
+
maxAttempts: { type: "number", min: 1 },
|
|
2983
|
+
performAction: { type: "boolean" },
|
|
2984
|
+
},
|
|
2985
|
+
custom(args, issues) {
|
|
2986
|
+
validateRequiredDocumentResolveArgs(args, issues);
|
|
2987
|
+
const hasMentions = Array.isArray(args.mentions) && args.mentions.length > 0;
|
|
2988
|
+
if (!args.text && !args.data && !hasMentions) {
|
|
2989
|
+
issues.push({ path: "args.text", message: "or args.data or args.mentions is required" });
|
|
2968
2990
|
}
|
|
2969
2991
|
},
|
|
2970
2992
|
},
|
package/src/tools.extended.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import fs from "node:fs/promises";
|
|
2
2
|
import path from "node:path";
|
|
3
|
-
import { createHash } from "node:crypto";
|
|
3
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
4
4
|
import { ApiError, CliError } from "./errors.js";
|
|
5
5
|
import { assertPerformAction } from "./action-gate.js";
|
|
6
6
|
import { defaultTmpDir } from "./config-store.js";
|
|
@@ -1003,6 +1003,345 @@ async function resolveAccessId(ctx, args = {}, input) {
|
|
|
1003
1003
|
};
|
|
1004
1004
|
}
|
|
1005
1005
|
|
|
1006
|
+
// ---------------------------------------------------------------------------
|
|
1007
|
+
// Comment ergonomics: plain/markdown text -> Outline ProseMirror `data` doc,
|
|
1008
|
+
// with first-class @-mention resolution.
|
|
1009
|
+
//
|
|
1010
|
+
// Outline stores comment bodies as a ProseMirror document under `data`, NOT a
|
|
1011
|
+
// plain `text` field (the API returns validation_error if only text is sent on
|
|
1012
|
+
// some deployments, and mentions are impossible without the doc form). Each
|
|
1013
|
+
// mention is a node: { type: "mention", attrs: { type: "user", modelId, label,
|
|
1014
|
+
// id, actorId } } where `id` is a fresh UUID per mention. Outline enforces a
|
|
1015
|
+
// 1000-character limit measured on the comment TEXT (not the JSON), returning
|
|
1016
|
+
// validation_error "Comment must be less than 1000 characters (data)".
|
|
1017
|
+
//
|
|
1018
|
+
// We accept a simple `text` body plus a `mentions` list (names / emails /
|
|
1019
|
+
// userIds) and build the doc ourselves. Mentions are resolved against the
|
|
1020
|
+
// users API by FIRST-NAME token + email (display-name order varies across
|
|
1021
|
+
// systems, e.g. Outline shows "Quan, Tran Le" while Jira shows "Tran Le Quan").
|
|
1022
|
+
// ---------------------------------------------------------------------------
|
|
1023
|
+
|
|
1024
|
+
const COMMENT_TEXT_LIMIT = 1000;
|
|
1025
|
+
|
|
1026
|
+
function commentTextNode(text) {
|
|
1027
|
+
return { type: "text", text };
|
|
1028
|
+
}
|
|
1029
|
+
|
|
1030
|
+
function commentMentionNode({ userId, label }) {
|
|
1031
|
+
return {
|
|
1032
|
+
type: "mention",
|
|
1033
|
+
attrs: {
|
|
1034
|
+
type: "user",
|
|
1035
|
+
modelId: userId,
|
|
1036
|
+
label: label || "user",
|
|
1037
|
+
id: randomUUID(),
|
|
1038
|
+
actorId: null,
|
|
1039
|
+
},
|
|
1040
|
+
};
|
|
1041
|
+
}
|
|
1042
|
+
|
|
1043
|
+
// Split plain/markdown text into paragraphs on blank lines, and keep single
|
|
1044
|
+
// newlines as hard breaks inside a paragraph (mirrors how a human pastes text).
|
|
1045
|
+
function splitCommentParagraphs(text) {
|
|
1046
|
+
const normalized = String(text == null ? "" : text).replace(/\r\n?/g, "\n");
|
|
1047
|
+
const blocks = normalized.split(/\n{2,}/);
|
|
1048
|
+
const paragraphs = [];
|
|
1049
|
+
for (const block of blocks) {
|
|
1050
|
+
if (block.trim().length === 0) {
|
|
1051
|
+
continue;
|
|
1052
|
+
}
|
|
1053
|
+
paragraphs.push(block.split("\n"));
|
|
1054
|
+
}
|
|
1055
|
+
return paragraphs;
|
|
1056
|
+
}
|
|
1057
|
+
|
|
1058
|
+
// Build the ProseMirror `data` doc for a comment from text + resolved mentions.
|
|
1059
|
+
// Resolved mentions (each { userId, label }) are inserted at the very start of
|
|
1060
|
+
// the first paragraph, followed by a space, then the text.
|
|
1061
|
+
function buildCommentData(text, resolvedMentions = []) {
|
|
1062
|
+
const paragraphs = splitCommentParagraphs(text);
|
|
1063
|
+
const mentionNodes = resolvedMentions.map((mention) => commentMentionNode(mention));
|
|
1064
|
+
|
|
1065
|
+
const content = [];
|
|
1066
|
+
if (paragraphs.length === 0 && mentionNodes.length === 0) {
|
|
1067
|
+
content.push({ type: "paragraph" });
|
|
1068
|
+
}
|
|
1069
|
+
|
|
1070
|
+
paragraphs.forEach((lines, paragraphIndex) => {
|
|
1071
|
+
const inline = [];
|
|
1072
|
+
if (paragraphIndex === 0 && mentionNodes.length > 0) {
|
|
1073
|
+
mentionNodes.forEach((node) => {
|
|
1074
|
+
inline.push(node);
|
|
1075
|
+
inline.push(commentTextNode(" "));
|
|
1076
|
+
});
|
|
1077
|
+
}
|
|
1078
|
+
lines.forEach((line, lineIndex) => {
|
|
1079
|
+
if (lineIndex > 0) {
|
|
1080
|
+
inline.push({ type: "br" });
|
|
1081
|
+
}
|
|
1082
|
+
if (line.length > 0) {
|
|
1083
|
+
inline.push(commentTextNode(line));
|
|
1084
|
+
}
|
|
1085
|
+
});
|
|
1086
|
+
content.push(inline.length > 0 ? { type: "paragraph", content: inline } : { type: "paragraph" });
|
|
1087
|
+
});
|
|
1088
|
+
|
|
1089
|
+
// Mentions with no text body at all: emit a single paragraph holding them.
|
|
1090
|
+
if (paragraphs.length === 0 && mentionNodes.length > 0) {
|
|
1091
|
+
const inline = [];
|
|
1092
|
+
mentionNodes.forEach((node, index) => {
|
|
1093
|
+
inline.push(node);
|
|
1094
|
+
if (index < mentionNodes.length - 1) {
|
|
1095
|
+
inline.push(commentTextNode(" "));
|
|
1096
|
+
}
|
|
1097
|
+
});
|
|
1098
|
+
content.push({ type: "paragraph", content: inline });
|
|
1099
|
+
}
|
|
1100
|
+
|
|
1101
|
+
return { type: "doc", content };
|
|
1102
|
+
}
|
|
1103
|
+
|
|
1104
|
+
// Character count of the human-readable comment text (mention labels count as
|
|
1105
|
+
// "@label", matching how Outline measures the 1000-char limit on the data doc).
|
|
1106
|
+
function commentTextLength(text, resolvedMentions = []) {
|
|
1107
|
+
const textLen = String(text == null ? "" : text).length;
|
|
1108
|
+
const mentionLen = resolvedMentions.reduce(
|
|
1109
|
+
(sum, mention) => sum + 1 + String(mention.label || "user").length + 1,
|
|
1110
|
+
0
|
|
1111
|
+
);
|
|
1112
|
+
return textLen + mentionLen;
|
|
1113
|
+
}
|
|
1114
|
+
|
|
1115
|
+
function firstNameToken(name) {
|
|
1116
|
+
return String(name || "")
|
|
1117
|
+
// "Last, First Middle" -> take the part after the comma first
|
|
1118
|
+
.split(",")
|
|
1119
|
+
.map((part) => part.trim())
|
|
1120
|
+
.filter(Boolean)
|
|
1121
|
+
.reverse()[0]
|
|
1122
|
+
?.split(/\s+/)
|
|
1123
|
+
.filter(Boolean)[0]
|
|
1124
|
+
?.toLowerCase() || "";
|
|
1125
|
+
}
|
|
1126
|
+
|
|
1127
|
+
function normalizeMentionToken(value) {
|
|
1128
|
+
return String(value || "").trim().toLowerCase();
|
|
1129
|
+
}
|
|
1130
|
+
|
|
1131
|
+
function looksLikeUuid(value) {
|
|
1132
|
+
return /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(
|
|
1133
|
+
String(value || "").trim()
|
|
1134
|
+
);
|
|
1135
|
+
}
|
|
1136
|
+
|
|
1137
|
+
function looksLikeEmail(value) {
|
|
1138
|
+
return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value || "").trim());
|
|
1139
|
+
}
|
|
1140
|
+
|
|
1141
|
+
// Pull the user rows out of a users.list response body (shape: { data: [...] }).
|
|
1142
|
+
function usersFromListBody(body) {
|
|
1143
|
+
if (Array.isArray(body)) {
|
|
1144
|
+
return body;
|
|
1145
|
+
}
|
|
1146
|
+
if (Array.isArray(body?.data)) {
|
|
1147
|
+
return body.data;
|
|
1148
|
+
}
|
|
1149
|
+
if (Array.isArray(body?.data?.users)) {
|
|
1150
|
+
return body.data.users;
|
|
1151
|
+
}
|
|
1152
|
+
return [];
|
|
1153
|
+
}
|
|
1154
|
+
|
|
1155
|
+
async function fetchWorkspaceUsers(ctx, { maxAttempts } = {}) {
|
|
1156
|
+
const collected = [];
|
|
1157
|
+
const limit = 100;
|
|
1158
|
+
let offset = 0;
|
|
1159
|
+
// Outline paginates users.list; pull a few pages to cover typical workspaces.
|
|
1160
|
+
for (let page = 0; page < 25; page += 1) {
|
|
1161
|
+
let res;
|
|
1162
|
+
try {
|
|
1163
|
+
res = await ctx.client.call("users.list", { limit, offset }, { maxAttempts: maxAttempts || 2 });
|
|
1164
|
+
} catch (err) {
|
|
1165
|
+
if (collected.length > 0) {
|
|
1166
|
+
break;
|
|
1167
|
+
}
|
|
1168
|
+
throw err;
|
|
1169
|
+
}
|
|
1170
|
+
const rows = usersFromListBody(res.body);
|
|
1171
|
+
collected.push(...rows);
|
|
1172
|
+
const pagination = res.body?.pagination;
|
|
1173
|
+
const total = Number(pagination?.total);
|
|
1174
|
+
if (rows.length < limit) {
|
|
1175
|
+
break;
|
|
1176
|
+
}
|
|
1177
|
+
offset += limit;
|
|
1178
|
+
if (Number.isFinite(total) && offset >= total) {
|
|
1179
|
+
break;
|
|
1180
|
+
}
|
|
1181
|
+
}
|
|
1182
|
+
return collected;
|
|
1183
|
+
}
|
|
1184
|
+
|
|
1185
|
+
// Resolve one mention token (name / email / userId) to { userId, label }.
|
|
1186
|
+
// Matching strategy:
|
|
1187
|
+
// - userId (uuid) -> exact id match
|
|
1188
|
+
// - email -> exact email match
|
|
1189
|
+
// - name -> FIRST-NAME token match (+ optional email disambiguation)
|
|
1190
|
+
// Returns { resolved } on success, or { error, candidates } on failure.
|
|
1191
|
+
function resolveMentionToken(token, users) {
|
|
1192
|
+
const raw = String(token || "").trim();
|
|
1193
|
+
if (!raw) {
|
|
1194
|
+
return { error: { value: token, status: "empty" } };
|
|
1195
|
+
}
|
|
1196
|
+
|
|
1197
|
+
if (looksLikeUuid(raw)) {
|
|
1198
|
+
const match = users.find((user) => normalizeMentionToken(user?.id) === normalizeMentionToken(raw));
|
|
1199
|
+
if (match) {
|
|
1200
|
+
return { resolved: { userId: match.id, label: match.name || match.email || "user" } };
|
|
1201
|
+
}
|
|
1202
|
+
return { error: { value: raw, status: "not_found", reason: "no user with that id" } };
|
|
1203
|
+
}
|
|
1204
|
+
|
|
1205
|
+
if (looksLikeEmail(raw)) {
|
|
1206
|
+
const match = users.find((user) => normalizeMentionToken(user?.email) === normalizeMentionToken(raw));
|
|
1207
|
+
if (match) {
|
|
1208
|
+
return { resolved: { userId: match.id, label: match.name || match.email || "user" } };
|
|
1209
|
+
}
|
|
1210
|
+
return { error: { value: raw, status: "not_found", reason: "no user with that email" } };
|
|
1211
|
+
}
|
|
1212
|
+
|
|
1213
|
+
// Name token: match on first-name token. Support "name <email>" / "name|email".
|
|
1214
|
+
const emailHint = raw.match(/[<|]\s*([^\s@<>|]+@[^\s@<>|]+)\s*>?/)?.[1];
|
|
1215
|
+
const namePart = emailHint ? raw.replace(/[<|]\s*[^\s@<>|]+@[^\s@<>|]+\s*>?/, "").trim() : raw;
|
|
1216
|
+
const wantFirst = firstNameToken(namePart);
|
|
1217
|
+
|
|
1218
|
+
let candidates = users.filter((user) => {
|
|
1219
|
+
const userFirst = firstNameToken(user?.name) || firstNameToken(user?.email);
|
|
1220
|
+
return userFirst && wantFirst && userFirst === wantFirst;
|
|
1221
|
+
});
|
|
1222
|
+
|
|
1223
|
+
if (emailHint) {
|
|
1224
|
+
const byEmail = candidates.filter(
|
|
1225
|
+
(user) => normalizeMentionToken(user?.email) === normalizeMentionToken(emailHint)
|
|
1226
|
+
);
|
|
1227
|
+
if (byEmail.length > 0) {
|
|
1228
|
+
candidates = byEmail;
|
|
1229
|
+
}
|
|
1230
|
+
}
|
|
1231
|
+
|
|
1232
|
+
if (candidates.length === 1) {
|
|
1233
|
+
const match = candidates[0];
|
|
1234
|
+
return { resolved: { userId: match.id, label: match.name || match.email || "user" } };
|
|
1235
|
+
}
|
|
1236
|
+
|
|
1237
|
+
if (candidates.length === 0) {
|
|
1238
|
+
return { error: { value: raw, status: "not_found", reason: "no user matched first name" } };
|
|
1239
|
+
}
|
|
1240
|
+
|
|
1241
|
+
return {
|
|
1242
|
+
error: {
|
|
1243
|
+
value: raw,
|
|
1244
|
+
status: "ambiguous",
|
|
1245
|
+
reason: "multiple users share that first name; pass an email or userId",
|
|
1246
|
+
candidates: candidates.map((user) => ({ id: user.id, name: user.name, email: user.email })),
|
|
1247
|
+
},
|
|
1248
|
+
};
|
|
1249
|
+
}
|
|
1250
|
+
|
|
1251
|
+
async function resolveMentions(ctx, mentions, { maxAttempts } = {}) {
|
|
1252
|
+
const tokens = ensureStringArray(mentions).map((item) => String(item).trim()).filter(Boolean);
|
|
1253
|
+
if (tokens.length === 0) {
|
|
1254
|
+
return { resolved: [], failures: [] };
|
|
1255
|
+
}
|
|
1256
|
+
const users = await fetchWorkspaceUsers(ctx, { maxAttempts });
|
|
1257
|
+
const resolved = [];
|
|
1258
|
+
const failures = [];
|
|
1259
|
+
for (const token of tokens) {
|
|
1260
|
+
const outcome = resolveMentionToken(token, users);
|
|
1261
|
+
if (outcome.resolved) {
|
|
1262
|
+
resolved.push(outcome.resolved);
|
|
1263
|
+
} else {
|
|
1264
|
+
failures.push(outcome.error);
|
|
1265
|
+
}
|
|
1266
|
+
}
|
|
1267
|
+
return { resolved, failures };
|
|
1268
|
+
}
|
|
1269
|
+
|
|
1270
|
+
// prepareBody hook for comments.create / comments.post. Runs AFTER document
|
|
1271
|
+
// resolution (so bodyArgs.documentId is set) and BEFORE the API call. Builds
|
|
1272
|
+
// the ProseMirror `data` doc from `text` + `mentions`, enforces the 1000-char
|
|
1273
|
+
// limit, and strips the convenience-only keys from the outgoing body.
|
|
1274
|
+
async function prepareCommentBody(ctx, def, args, bodyArgs) {
|
|
1275
|
+
const text = typeof bodyArgs.text === "string" ? bodyArgs.text : "";
|
|
1276
|
+
const hasMentions = Array.isArray(args.mentions) && args.mentions.length > 0;
|
|
1277
|
+
const hasExplicitData = bodyArgs.data !== undefined && bodyArgs.data !== null;
|
|
1278
|
+
|
|
1279
|
+
// Caller passed a pre-built ProseMirror doc and no mentions: passthrough,
|
|
1280
|
+
// just drop the convenience-only `mentions` key if present.
|
|
1281
|
+
if (hasExplicitData && !hasMentions && !text) {
|
|
1282
|
+
delete bodyArgs.mentions;
|
|
1283
|
+
return bodyArgs;
|
|
1284
|
+
}
|
|
1285
|
+
|
|
1286
|
+
let resolvedMentions = [];
|
|
1287
|
+
if (hasMentions) {
|
|
1288
|
+
const maxAttempts = toInteger(args.maxAttempts, 2);
|
|
1289
|
+
const { resolved, failures } = await resolveMentions(ctx, args.mentions, { maxAttempts });
|
|
1290
|
+
if (failures.length > 0) {
|
|
1291
|
+
throw new CliError(
|
|
1292
|
+
`comments.${def.tool.endsWith(".post") ? "post" : "create"}: could not resolve ${failures.length} mention(s): ` +
|
|
1293
|
+
failures.map((f) => `"${f.value}" (${f.status})`).join(", "),
|
|
1294
|
+
{
|
|
1295
|
+
code: "MENTION_UNRESOLVED",
|
|
1296
|
+
tool: def.tool,
|
|
1297
|
+
failures,
|
|
1298
|
+
}
|
|
1299
|
+
);
|
|
1300
|
+
}
|
|
1301
|
+
resolvedMentions = resolved;
|
|
1302
|
+
}
|
|
1303
|
+
|
|
1304
|
+
// Enforce the 1000-char limit on the human text (not the JSON), pre-flight.
|
|
1305
|
+
const length = commentTextLength(text, resolvedMentions);
|
|
1306
|
+
if (length > COMMENT_TEXT_LIMIT) {
|
|
1307
|
+
throw new CliError(
|
|
1308
|
+
`comments.${def.tool.endsWith(".post") ? "post" : "create"}: comment text is ${length} characters; Outline allows at most ${COMMENT_TEXT_LIMIT}.`,
|
|
1309
|
+
{
|
|
1310
|
+
code: "COMMENT_TOO_LONG",
|
|
1311
|
+
tool: def.tool,
|
|
1312
|
+
length,
|
|
1313
|
+
limit: COMMENT_TEXT_LIMIT,
|
|
1314
|
+
}
|
|
1315
|
+
);
|
|
1316
|
+
}
|
|
1317
|
+
|
|
1318
|
+
// If the caller gave an explicit data doc AND mentions, prepend mention nodes
|
|
1319
|
+
// to its first paragraph; otherwise build from text.
|
|
1320
|
+
if (hasExplicitData && resolvedMentions.length > 0) {
|
|
1321
|
+
const doc = bodyArgs.data;
|
|
1322
|
+
const mentionNodes = resolvedMentions.flatMap((mention) => [
|
|
1323
|
+
commentMentionNode(mention),
|
|
1324
|
+
commentTextNode(" "),
|
|
1325
|
+
]);
|
|
1326
|
+
const firstParagraph = Array.isArray(doc?.content)
|
|
1327
|
+
? doc.content.find((node) => node?.type === "paragraph")
|
|
1328
|
+
: null;
|
|
1329
|
+
if (firstParagraph) {
|
|
1330
|
+
firstParagraph.content = [...mentionNodes, ...(firstParagraph.content || [])];
|
|
1331
|
+
} else if (doc && Array.isArray(doc.content)) {
|
|
1332
|
+
doc.content.unshift({ type: "paragraph", content: mentionNodes });
|
|
1333
|
+
}
|
|
1334
|
+
bodyArgs.data = doc;
|
|
1335
|
+
} else if (!hasExplicitData) {
|
|
1336
|
+
bodyArgs.data = buildCommentData(text, resolvedMentions);
|
|
1337
|
+
}
|
|
1338
|
+
|
|
1339
|
+
// Outline wants `data`, not `text` — drop the convenience keys.
|
|
1340
|
+
delete bodyArgs.text;
|
|
1341
|
+
delete bodyArgs.mentions;
|
|
1342
|
+
return bodyArgs;
|
|
1343
|
+
}
|
|
1344
|
+
|
|
1006
1345
|
function makeRpcHandler(def) {
|
|
1007
1346
|
return async function rpcHandler(ctx, args = {}) {
|
|
1008
1347
|
if (def.mutating) {
|
|
@@ -1049,6 +1388,12 @@ function makeRpcHandler(def) {
|
|
|
1049
1388
|
omitKeys.push(...(item.omitKeys || []));
|
|
1050
1389
|
}
|
|
1051
1390
|
const effectiveOmitKeys = omitKeys.filter((key) => !resolvedOutputFields.has(key));
|
|
1391
|
+
if (typeof def.prepareBody === "function") {
|
|
1392
|
+
// Hook runs after target resolution (documentId is set) and before the
|
|
1393
|
+
// API call, letting a def transform the outgoing body (e.g. comments
|
|
1394
|
+
// build a ProseMirror data doc + resolve @-mentions).
|
|
1395
|
+
await def.prepareBody(ctx, def, args, bodyArgs);
|
|
1396
|
+
}
|
|
1052
1397
|
const body = buildBody(
|
|
1053
1398
|
bodyArgs,
|
|
1054
1399
|
effectiveOmitKeys.length > 0
|
|
@@ -1300,7 +1645,24 @@ const RPC_WRAPPER_DEFS = [
|
|
|
1300
1645
|
{
|
|
1301
1646
|
tool: "comments.list",
|
|
1302
1647
|
method: "comments.list",
|
|
1303
|
-
description:
|
|
1648
|
+
description:
|
|
1649
|
+
"List comments on a document (and their replies). Resolve the target with documentId/query/refs/url/urlId. Use includeReplies=true to nest replies, or parentCommentId to fetch the replies of one thread.",
|
|
1650
|
+
signature:
|
|
1651
|
+
"comments.list(args?: { documentId?: string; query?: string; documentQuery?: string; refs?: string[]; shareId?: string; urlId?: string; url?: string; parentCommentId?: string; includeReplies?: boolean; includeAnchorText?: boolean; limit?: number; offset?: number; sort?: string; direction?: 'ASC'|'DESC'; includePolicies?: boolean; view?: 'ids'|'summary'|'full'; maxAttempts?: number })",
|
|
1652
|
+
usageExample: {
|
|
1653
|
+
tool: "comments.list",
|
|
1654
|
+
args: {
|
|
1655
|
+
query: "incident runbook",
|
|
1656
|
+
includeReplies: true,
|
|
1657
|
+
limit: 50,
|
|
1658
|
+
},
|
|
1659
|
+
},
|
|
1660
|
+
bestPractices: [
|
|
1661
|
+
"Pass documentId for exact calls, or query/refs/url/urlId to resolve a remembered document first.",
|
|
1662
|
+
"Set includeReplies=true to fetch replies nested under each top-level comment.",
|
|
1663
|
+
"Pass parentCommentId to read the replies of a specific comment (e.g. after posting one).",
|
|
1664
|
+
"Use view='ids' or 'summary' to keep responses token-efficient.",
|
|
1665
|
+
],
|
|
1304
1666
|
resolveAccess: {
|
|
1305
1667
|
kind: "document",
|
|
1306
1668
|
outputField: "documentId",
|
|
@@ -1314,24 +1676,62 @@ const RPC_WRAPPER_DEFS = [
|
|
|
1314
1676
|
{
|
|
1315
1677
|
tool: "comments.create",
|
|
1316
1678
|
method: "comments.create",
|
|
1317
|
-
description:
|
|
1679
|
+
description:
|
|
1680
|
+
"Post a comment on a document. Pass plain/markdown `text` and the ProseMirror `data` doc is built for you; pass `mentions` (names/emails/userIds) to auto-insert @-mentions. Use `parentCommentId` to reply.",
|
|
1318
1681
|
signature:
|
|
1319
|
-
"comments.create(args: { documentId?: string; query?: string; documentQuery?: string; refs?: string[]; shareId?: string; urlId?: string; url?: string; text?: string; data?: object; parentCommentId?: string; includePolicies?: boolean; view?: 'summary'|'full'; maxAttempts?: number; performAction?: boolean })",
|
|
1682
|
+
"comments.create(args: { documentId?: string; query?: string; documentQuery?: string; refs?: string[]; shareId?: string; urlId?: string; url?: string; text?: string; mentions?: string[]; data?: object; parentCommentId?: string; includePolicies?: boolean; view?: 'summary'|'full'; maxAttempts?: number; performAction?: boolean })",
|
|
1320
1683
|
usageExample: {
|
|
1321
1684
|
tool: "comments.create",
|
|
1322
1685
|
args: {
|
|
1323
1686
|
query: "incident runbook",
|
|
1324
|
-
text: "
|
|
1687
|
+
text: "Please review the rollback steps.",
|
|
1688
|
+
mentions: ["Tran Le Quan", "alice@example.com"],
|
|
1689
|
+
performAction: true,
|
|
1690
|
+
},
|
|
1691
|
+
},
|
|
1692
|
+
bestPractices: [
|
|
1693
|
+
"Pass plain/markdown `text`; the ProseMirror `data` doc is built for you (blank lines split paragraphs, single newlines become line breaks).",
|
|
1694
|
+
"Pass `mentions` as a list of names, emails, or userIds; names match on FIRST NAME (e.g. \"Tran Le Quan\" matches Outline's \"Quan, Tran Le\"). Ambiguous names are rejected with candidates — disambiguate with an email or userId.",
|
|
1695
|
+
"Comment text is capped at 1000 characters (pre-flight check on text, not JSON).",
|
|
1696
|
+
"Pass query/refs/url/urlId to comment on a remembered document without a separate lookup.",
|
|
1697
|
+
"Use parentCommentId to reply to an existing comment.",
|
|
1698
|
+
"Advanced: pass a raw ProseMirror `data` doc to bypass text building (mentions are still prepended if provided).",
|
|
1699
|
+
"This tool is action-gated; set performAction=true only for explicitly confirmed mutations.",
|
|
1700
|
+
],
|
|
1701
|
+
mutating: true,
|
|
1702
|
+
prepareBody: prepareCommentBody,
|
|
1703
|
+
resolveAccess: {
|
|
1704
|
+
kind: "document",
|
|
1705
|
+
outputField: "documentId",
|
|
1706
|
+
exactKeys: ["documentId"],
|
|
1707
|
+
required: true,
|
|
1708
|
+
queryKeys: ["query", "documentQuery", "documentRef", "shareId", "urlId", "url"],
|
|
1709
|
+
arrayQueryKeys: ["queries", "documentQueries", "documentRefs", "refs", "shareIds", "urlIds", "urls"],
|
|
1710
|
+
},
|
|
1711
|
+
},
|
|
1712
|
+
{
|
|
1713
|
+
tool: "comments.post",
|
|
1714
|
+
method: "comments.create",
|
|
1715
|
+
description:
|
|
1716
|
+
"Convenience alias of comments.create: post a comment from plain `text` + ergonomic `mentions`. The ProseMirror data doc and @-mention nodes are built for you.",
|
|
1717
|
+
signature:
|
|
1718
|
+
"comments.post(args: { documentId?: string; query?: string; documentQuery?: string; refs?: string[]; shareId?: string; urlId?: string; url?: string; text?: string; mentions?: string[]; data?: object; parentCommentId?: string; includePolicies?: boolean; view?: 'summary'|'full'; maxAttempts?: number; performAction?: boolean })",
|
|
1719
|
+
usageExample: {
|
|
1720
|
+
tool: "comments.post",
|
|
1721
|
+
args: {
|
|
1722
|
+
query: "incident runbook",
|
|
1723
|
+
text: "Can you confirm the timeline?",
|
|
1724
|
+
mentions: ["Quan"],
|
|
1325
1725
|
performAction: true,
|
|
1326
1726
|
},
|
|
1327
1727
|
},
|
|
1328
1728
|
bestPractices: [
|
|
1329
|
-
"
|
|
1330
|
-
"
|
|
1331
|
-
"Inspect the returned documentId and resolution fields when the target was resolved from memory.",
|
|
1729
|
+
"Same as comments.create: simple `text` + `mentions` (names/emails/userIds), 1000-char limit, parentCommentId for replies.",
|
|
1730
|
+
"Names resolve on FIRST NAME + email; ambiguous names error with candidates.",
|
|
1332
1731
|
"This tool is action-gated; set performAction=true only for explicitly confirmed mutations.",
|
|
1333
1732
|
],
|
|
1334
1733
|
mutating: true,
|
|
1734
|
+
prepareBody: prepareCommentBody,
|
|
1335
1735
|
resolveAccess: {
|
|
1336
1736
|
kind: "document",
|
|
1337
1737
|
outputField: "documentId",
|
|
@@ -5357,6 +5757,18 @@ async function federatedPermissionSnapshotTool(ctx, args = {}) {
|
|
|
5357
5757
|
};
|
|
5358
5758
|
}
|
|
5359
5759
|
|
|
5760
|
+
// Exported for unit testing the comment data-builder and mention-resolver
|
|
5761
|
+
// without hitting the network.
|
|
5762
|
+
export const __commentInternals = {
|
|
5763
|
+
COMMENT_TEXT_LIMIT,
|
|
5764
|
+
buildCommentData,
|
|
5765
|
+
commentTextLength,
|
|
5766
|
+
splitCommentParagraphs,
|
|
5767
|
+
firstNameToken,
|
|
5768
|
+
resolveMentionToken,
|
|
5769
|
+
usersFromListBody,
|
|
5770
|
+
};
|
|
5771
|
+
|
|
5360
5772
|
export const EXTENDED_TOOLS = {
|
|
5361
5773
|
...RPC_TOOLS,
|
|
5362
5774
|
"documents.answer": {
|