@khanglvm/outline-cli 0.1.5 → 0.1.7

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.
@@ -1,8 +1,10 @@
1
1
  import fs from "node:fs/promises";
2
2
  import path from "node:path";
3
+ import { createHash } from "node:crypto";
3
4
  import { ApiError, CliError } from "./errors.js";
4
5
  import { assertPerformAction } from "./action-gate.js";
5
- import { compactValue, ensureStringArray, mapLimit, toInteger } from "./utils.js";
6
+ import { defaultTmpDir } from "./config-store.js";
7
+ import { compactValue, ensureStringArray, mapLimit, sanitizeFileToken, toInteger } from "./utils.js";
6
8
 
7
9
  const CONTROL_ARG_KEYS = new Set([
8
10
  "performAction",
@@ -53,6 +55,201 @@ function appendMultipartValue(form, key, value) {
53
55
  form.append(key, String(value));
54
56
  }
55
57
 
58
+ const ATTACHMENT_REDIRECT_PATTERN =
59
+ /((?:https?:\/\/[^\s)"']+)?\/api\/attachments\.redirect\?[^)\s"']*?\bid=([0-9a-fA-F-]{36})[^)\s"']*)/g;
60
+
61
+ const EXT_BY_CONTENT_TYPE = new Map([
62
+ ["image/png", ".png"],
63
+ ["image/jpeg", ".jpg"],
64
+ ["image/gif", ".gif"],
65
+ ["image/webp", ".webp"],
66
+ ["image/svg+xml", ".svg"],
67
+ ["application/pdf", ".pdf"],
68
+ ["text/plain", ".txt"],
69
+ ["text/markdown", ".md"],
70
+ ["application/json", ".json"],
71
+ ["application/zip", ".zip"],
72
+ ]);
73
+
74
+ function getHeader(headers = {}, name) {
75
+ const target = String(name || "").toLowerCase();
76
+ for (const [key, value] of Object.entries(headers || {})) {
77
+ if (String(key).toLowerCase() === target) {
78
+ return value;
79
+ }
80
+ }
81
+ return undefined;
82
+ }
83
+
84
+ function contentTypeToExtension(contentType) {
85
+ const normalized = String(contentType || "").split(";")[0].trim().toLowerCase();
86
+ return EXT_BY_CONTENT_TYPE.get(normalized) || ".bin";
87
+ }
88
+
89
+ function parseContentDispositionFilename(value) {
90
+ const raw = String(value || "");
91
+ const encoded = raw.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
92
+ if (encoded) {
93
+ try {
94
+ return decodeURIComponent(encoded);
95
+ } catch {
96
+ return encoded;
97
+ }
98
+ }
99
+ return raw.match(/filename="?([^";]+)"?/i)?.[1] || "";
100
+ }
101
+
102
+ function extractAttachmentId(value) {
103
+ const raw = String(value || "").trim();
104
+ if (!raw) {
105
+ return "";
106
+ }
107
+ if (/^[0-9a-fA-F-]{36}$/.test(raw)) {
108
+ return raw.toLowerCase();
109
+ }
110
+
111
+ try {
112
+ const parsed = new URL(raw, "https://outline.local");
113
+ const id = parsed.searchParams.get("id");
114
+ return id && /^[0-9a-fA-F-]{36}$/.test(id) ? id.toLowerCase() : "";
115
+ } catch {
116
+ const match = raw.match(/\bid=([0-9a-fA-F-]{36})\b/);
117
+ return match ? match[1].toLowerCase() : "";
118
+ }
119
+ }
120
+
121
+ function extractDocumentUrlId(value) {
122
+ const raw = String(value || "").trim();
123
+ if (!raw) {
124
+ return "";
125
+ }
126
+
127
+ try {
128
+ const parsed = new URL(raw);
129
+ const last = parsed.pathname.split("/").filter(Boolean).pop() || "";
130
+ return last.match(/-([A-Za-z0-9]{8,})$/)?.[1] || "";
131
+ } catch {
132
+ return raw.match(/-([A-Za-z0-9]{8,})$/)?.[1] || "";
133
+ }
134
+ }
135
+
136
+ function extractAttachmentRefsFromText(text, baseUrl = "") {
137
+ const refs = [];
138
+ const seen = new Set();
139
+ const source = String(text || "");
140
+ const base = String(baseUrl || "").replace(/\/+$/, "");
141
+ const pattern = new RegExp(ATTACHMENT_REDIRECT_PATTERN.source, "g");
142
+ let match;
143
+
144
+ while ((match = pattern.exec(source)) !== null) {
145
+ const id = extractAttachmentId(match[1]);
146
+ if (!id || seen.has(id)) {
147
+ continue;
148
+ }
149
+ seen.add(id);
150
+ const url = match[1];
151
+ refs.push({
152
+ id,
153
+ index: refs.length,
154
+ source: "markdown",
155
+ url,
156
+ absoluteUrl: url.startsWith("http") || !base ? url : `${base}${url}`,
157
+ position: match.index,
158
+ });
159
+ }
160
+
161
+ return refs;
162
+ }
163
+
164
+ async function readDocumentForAttachments(ctx, args = {}) {
165
+ const id = args.id || args.documentId || extractDocumentUrlId(args.url);
166
+ const shareId = args.shareId;
167
+ if (!id && !shareId) {
168
+ throw new CliError("document attachment tools require args.id, args.documentId, args.url, or args.shareId");
169
+ }
170
+
171
+ const body = compactValue({ id, shareId }) || {};
172
+ const res = await ctx.client.call("documents.info", body, {
173
+ maxAttempts: toInteger(args.maxAttempts, 2),
174
+ });
175
+ const doc = res.body?.data || null;
176
+ if (!doc) {
177
+ throw new CliError("documents.info response did not include document data");
178
+ }
179
+ return doc;
180
+ }
181
+
182
+ function summarizeAttachmentDocument(doc) {
183
+ return {
184
+ id: doc?.id,
185
+ title: doc?.title,
186
+ url: doc?.url,
187
+ urlId: doc?.urlId,
188
+ collectionId: doc?.collectionId,
189
+ parentDocumentId: doc?.parentDocumentId,
190
+ revision: doc?.revision,
191
+ updatedAt: doc?.updatedAt,
192
+ };
193
+ }
194
+
195
+ function resolveAttachmentOutputPath(args, id, headers, index = null) {
196
+ if (args.filePath) {
197
+ return path.resolve(String(args.filePath));
198
+ }
199
+
200
+ const contentType = getHeader(headers, "content-type");
201
+ const dispositionName = parseContentDispositionFilename(getHeader(headers, "content-disposition"));
202
+ const requestedName = typeof args.fileName === "string" ? args.fileName.trim() : "";
203
+ const baseName = requestedName || dispositionName;
204
+ const ext = path.extname(baseName) || contentTypeToExtension(contentType);
205
+ const prefix = index === null ? "" : `${String(index + 1).padStart(2, "0")}-`;
206
+ const fallbackName = `${prefix}${id}${ext}`;
207
+ const safeName = sanitizeFileToken(baseName ? `${prefix}${baseName}` : fallbackName);
208
+ const outputDir = path.resolve(String(args.outputDir || path.join(defaultTmpDir(), "attachments")));
209
+
210
+ return path.join(outputDir, safeName);
211
+ }
212
+
213
+ async function writeAttachmentFile(filePath, buffer, overwrite) {
214
+ await fs.mkdir(path.dirname(filePath), { recursive: true });
215
+ try {
216
+ await fs.writeFile(filePath, buffer, { flag: overwrite ? "w" : "wx" });
217
+ } catch (err) {
218
+ if (err?.code === "EEXIST") {
219
+ throw new CliError(`Attachment file already exists: ${filePath}`, {
220
+ code: "ATTACHMENT_FILE_EXISTS",
221
+ filePath,
222
+ });
223
+ }
224
+ throw err;
225
+ }
226
+ }
227
+
228
+ async function downloadAttachmentToFile(ctx, args = {}, id, index = null) {
229
+ if (!ctx.client || typeof ctx.client.download !== "function") {
230
+ throw new CliError("Current Outline client does not support binary downloads");
231
+ }
232
+
233
+ const res = await ctx.client.download("attachments.redirect", { id }, {
234
+ maxAttempts: toInteger(args.maxAttempts, 2),
235
+ });
236
+ const buffer = res.body;
237
+ const filePath = resolveAttachmentOutputPath(args, id, res.headers, index);
238
+ await writeAttachmentFile(filePath, buffer, args.overwrite === true);
239
+
240
+ const contentType = getHeader(res.headers, "content-type") || "application/octet-stream";
241
+ return {
242
+ id,
243
+ ok: true,
244
+ filePath,
245
+ bytes: buffer.length,
246
+ sha256: createHash("sha256").update(buffer).digest("hex"),
247
+ contentType,
248
+ status: res.status,
249
+ sourceUrl: res.url,
250
+ };
251
+ }
252
+
56
253
  function defaultUsageArgs(def) {
57
254
  if (def.tool === "documents.empty_trash") {
58
255
  return def.mutating ? { performAction: true } : {};
@@ -408,10 +605,39 @@ async function buildAnswerFallbackResult(ctx, question, args = {}) {
408
605
  const maxAttempts = Math.max(1, toInteger(args.maxAttempts, 2));
409
606
  const contextChars = Math.max(80, toInteger(args.contextChars, 220));
410
607
  const limit = Math.max(1, Math.min(8, toInteger(args.limit, 5)));
608
+ const scopedDocumentId = args.documentId || args.id;
609
+
610
+ if (scopedDocumentId) {
611
+ const res = await ctx.client.call("documents.info", { id: scopedDocumentId }, { maxAttempts });
612
+ const document = normalizeFallbackAnswerHit(res.body?.data, contextChars);
613
+ return {
614
+ question,
615
+ answer: "",
616
+ noAnswerReason: "documents.answerQuestion is unsupported by this Outline deployment; returning the scoped document as retrieval evidence instead.",
617
+ unsupported: true,
618
+ fallbackUsed: true,
619
+ fallbackTool: "documents.info",
620
+ fallbackSuggestion: {
621
+ tool: "documents.info",
622
+ args: compactValue({
623
+ id: scopedDocumentId,
624
+ view: "summary",
625
+ }),
626
+ },
627
+ documents: document ? [document] : [],
628
+ retrieval: {
629
+ query: question,
630
+ result: compactValue({
631
+ ...maybeDropPolicies(res.body, !!args.includePolicies),
632
+ data: document,
633
+ }),
634
+ },
635
+ };
636
+ }
637
+
411
638
  const body = compactValue({
412
639
  query: question,
413
640
  collectionId: args.collectionId,
414
- documentId: args.documentId || args.id,
415
641
  userId: args.userId,
416
642
  shareId: args.shareId,
417
643
  statusFilter: args.statusFilter,
@@ -535,16 +761,30 @@ async function documentsAnswerBatchTool(ctx, args = {}) {
535
761
  };
536
762
  } catch (err) {
537
763
  if (parsed && isAnswerEndpointUnsupported(err)) {
538
- return {
539
- index,
540
- ok: true,
541
- question: parsed.question,
542
- documentId: parsed.documentId,
543
- result: await buildAnswerFallbackResult(ctx, parsed.question, {
544
- ...args,
545
- ...parsed.body,
546
- }),
547
- };
764
+ try {
765
+ return {
766
+ index,
767
+ ok: true,
768
+ question: parsed.question,
769
+ documentId: parsed.documentId,
770
+ result: await buildAnswerFallbackResult(ctx, parsed.question, {
771
+ ...args,
772
+ ...parsed.body,
773
+ }),
774
+ };
775
+ } catch (fallbackErr) {
776
+ if (fallbackErr instanceof ApiError || fallbackErr instanceof CliError) {
777
+ return {
778
+ index,
779
+ ok: false,
780
+ question: parsed.question,
781
+ documentId: parsed.documentId,
782
+ error: fallbackErr.message,
783
+ status: fallbackErr instanceof ApiError ? fallbackErr.details.status : undefined,
784
+ };
785
+ }
786
+ throw fallbackErr;
787
+ }
548
788
  }
549
789
  if (err instanceof ApiError || err instanceof CliError) {
550
790
  return {
@@ -574,6 +814,73 @@ async function documentsAnswerBatchTool(ctx, args = {}) {
574
814
  };
575
815
  }
576
816
 
817
+ async function documentsAttachmentsTool(ctx, args = {}) {
818
+ const doc = await readDocumentForAttachments(ctx, args);
819
+ const attachments = extractAttachmentRefsFromText(doc.text || "", ctx.profile?.baseUrl);
820
+
821
+ return {
822
+ tool: "documents.attachments",
823
+ profile: ctx.profile.id,
824
+ result: {
825
+ document: summarizeAttachmentDocument(doc),
826
+ total: attachments.length,
827
+ attachments,
828
+ },
829
+ };
830
+ }
831
+
832
+ async function attachmentsDownloadTool(ctx, args = {}) {
833
+ const id = extractAttachmentId(args.id || args.attachmentId || args.url || args.path);
834
+ if (!id) {
835
+ throw new CliError("attachments.download requires args.id or an attachment redirect args.url/path");
836
+ }
837
+
838
+ return {
839
+ tool: "attachments.download",
840
+ profile: ctx.profile.id,
841
+ result: await downloadAttachmentToFile(ctx, args, id),
842
+ };
843
+ }
844
+
845
+ async function documentsDownloadAttachmentsTool(ctx, args = {}) {
846
+ const doc = await readDocumentForAttachments(ctx, args);
847
+ const attachments = extractAttachmentRefsFromText(doc.text || "", ctx.profile?.baseUrl);
848
+ const concurrency = Math.max(1, Math.min(8, toInteger(args.concurrency, 3)));
849
+ const items = await mapLimit(attachments, concurrency, async (attachment, index) => {
850
+ try {
851
+ const saved = await downloadAttachmentToFile(ctx, args, attachment.id, index);
852
+ return {
853
+ ...attachment,
854
+ ...saved,
855
+ };
856
+ } catch (err) {
857
+ if (err instanceof ApiError || err instanceof CliError) {
858
+ return {
859
+ ...attachment,
860
+ ok: false,
861
+ error: err.message,
862
+ status: err instanceof ApiError ? err.details.status : undefined,
863
+ };
864
+ }
865
+ throw err;
866
+ }
867
+ });
868
+ const failed = items.filter((item) => !item.ok).length;
869
+
870
+ return {
871
+ tool: "documents.download_attachments",
872
+ profile: ctx.profile.id,
873
+ result: {
874
+ document: summarizeAttachmentDocument(doc),
875
+ total: attachments.length,
876
+ succeeded: items.length - failed,
877
+ failed,
878
+ outputDir: path.resolve(String(args.outputDir || path.join(defaultTmpDir(), "attachments"))),
879
+ items,
880
+ },
881
+ };
882
+ }
883
+
577
884
  async function documentsImportFileTool(ctx, args = {}) {
578
885
  assertPerformAction(args, {
579
886
  tool: "documents.import_file",
@@ -3217,6 +3524,64 @@ export const EXTENDED_TOOLS = {
3217
3524
  ],
3218
3525
  handler: documentsIssueRefReportTool,
3219
3526
  },
3527
+ "documents.attachments": {
3528
+ signature:
3529
+ "documents.attachments(args: { id?: string; documentId?: string; url?: string; shareId?: string; maxAttempts?: number })",
3530
+ description:
3531
+ "Extract embedded Outline attachment references from a document body, including images rendered through /api/attachments.redirect.",
3532
+ usageExample: {
3533
+ tool: "documents.attachments",
3534
+ args: {
3535
+ url: "https://handbook.example.com/doc/example-title-AbCdEf1234",
3536
+ },
3537
+ },
3538
+ bestPractices: [
3539
+ "Use this after documents.info when you need to enumerate embedded images or file links without downloading bytes.",
3540
+ "Pass a document URL directly; the tool resolves the Outline URL id suffix through documents.info.",
3541
+ "Follow with attachments.download or documents.download_attachments to save files locally.",
3542
+ ],
3543
+ handler: documentsAttachmentsTool,
3544
+ },
3545
+ "attachments.download": {
3546
+ signature:
3547
+ "attachments.download(args: { id?: string; attachmentId?: string; url?: string; path?: string; outputDir?: string; filePath?: string; fileName?: string; overwrite?: boolean; maxAttempts?: number })",
3548
+ description:
3549
+ "Download one Outline attachment or embedded image through the authenticated attachments.redirect endpoint and save it locally.",
3550
+ usageExample: {
3551
+ tool: "attachments.download",
3552
+ args: {
3553
+ id: "15831936-7fef-4a58-b17b-121a65c3d787",
3554
+ outputDir: "./outline-attachments",
3555
+ overwrite: true,
3556
+ },
3557
+ },
3558
+ bestPractices: [
3559
+ "Prefer id for deterministic downloads; url/path may be an /api/attachments.redirect?id=... value copied from document markdown.",
3560
+ "Use outputDir for generated names or filePath when the caller needs an exact path.",
3561
+ "Inspect returned sha256, bytes, and contentType before handing the file to downstream tools.",
3562
+ ],
3563
+ handler: attachmentsDownloadTool,
3564
+ },
3565
+ "documents.download_attachments": {
3566
+ signature:
3567
+ "documents.download_attachments(args: { id?: string; documentId?: string; url?: string; shareId?: string; outputDir?: string; overwrite?: boolean; concurrency?: number; maxAttempts?: number })",
3568
+ description:
3569
+ "Extract all embedded Outline attachment references from a document and save each referenced file locally.",
3570
+ usageExample: {
3571
+ tool: "documents.download_attachments",
3572
+ args: {
3573
+ url: "https://handbook.example.com/doc/example-title-AbCdEf1234",
3574
+ outputDir: "./outline-attachments",
3575
+ overwrite: true,
3576
+ },
3577
+ },
3578
+ bestPractices: [
3579
+ "Run documents.attachments first when you only need metadata or want to choose a subset.",
3580
+ "Keep concurrency modest for large image-heavy documents to avoid rate limits.",
3581
+ "Use overwrite=true for repeatable automation into a scratch directory.",
3582
+ ],
3583
+ handler: documentsDownloadAttachmentsTool,
3584
+ },
3220
3585
  "documents.import_file": {
3221
3586
  signature:
3222
3587
  "documents.import_file(args: { filePath: string; collectionId?: string; parentDocumentId?: string; publish?: boolean; contentType?: string; includePolicies?: boolean; maxAttempts?: number; performAction?: boolean; ...endpointArgs })",
package/.env.test.example DELETED
@@ -1,2 +0,0 @@
1
- OUTLINE_TEST_BASE_URL=https://example.getoutline.site
2
- OUTLINE_TEST_API_KEY=ol_api_replace_me
package/AGENTS.md DELETED
@@ -1,107 +0,0 @@
1
- # AGENTS.md
2
-
3
- ## Scope
4
- This repository contains `outline-cli` (`outline-agent` alias), a Node.js CLI optimized for AI agents to interact with Outline via real API calls.
5
-
6
- ## Core Principles
7
- - Keep outputs deterministic and machine-readable.
8
- - Optimize for low-token workflows (`summary/ids` views first, hydrate later).
9
- - Prefer batch operations for fewer round trips.
10
- - Never mutate existing workspace content in tests except suite-created test documents.
11
- - Keep security strict: no hardcoded live secrets in tracked files.
12
-
13
- ## Runtime + Commands
14
- - Node.js: `>=18.17`
15
- - Install: `npm install`
16
- - Basic check: `npm run check`
17
- - Full tests (real environment): `npm test`
18
-
19
- ## Repository Map
20
- - CLI entrypoint: `bin/outline-cli.js`
21
- - Command wiring/output modes: `src/cli.js`
22
- - API client/auth/retry: `src/outline-client.js`
23
- - Tool registry/core tools: `src/tools.js`
24
- - Navigation/search tools: `src/tools.navigation.js`
25
- - Mutation/revision tools: `src/tools.mutation.js`
26
- - Platform/cleanup/capabilities tools: `src/tools.platform.js`
27
- - Tool arg validation: `src/tool-arg-schemas.js`
28
- - Live integration tests: `test/live.integration.test.js`
29
-
30
- ## Local Environment
31
- - Template: `.env.test.example`
32
- - Local secret file (untracked): `.env.test.local`
33
- - Required vars for live tests:
34
- - `OUTLINE_TEST_BASE_URL`
35
- - `OUTLINE_TEST_API_KEY`
36
-
37
- ## Development Workflow
38
- 1. Pull latest branch and inspect current tool contracts:
39
- - `node ./bin/outline-cli.js tools contract all --result-mode inline`
40
- 2. Refresh raw API method inventory from prior sessions / wrappers, then diff wrapped vs raw:
41
- - `rg -o 'client\\.call\\(\"[^\"]+\"' src | sed -E 's/.*\\(\"//; s/\"$//' | sort | uniq`
42
- - record missing high-value endpoints in `/tmp/knowledges/outline-raw-api-gap.md`
43
- 3. Implement minimal, compatible changes (preserve response envelopes).
44
- 4. Add/adjust arg schema in `src/tool-arg-schemas.js` for every new tool arg.
45
- 5. Add/adjust real integration tests in `test/live.integration.test.js`.
46
- 6. Run:
47
- - `npm run check`
48
- - `npm test`
49
- 7. Update docs when behavior/signature changes:
50
- - `README.md`
51
- - `docs/TOOL_CONTRACTS.md`
52
-
53
- ## Testing Rules (Live Env)
54
- - No mocks when endpoint can be exercised live.
55
- - Mutation tests must:
56
- - create a dedicated test doc first,
57
- - perform all edits/patch/revision operations on that doc,
58
- - delete it in cleanup.
59
- - Read-only tools (search/list/info) may use site-wide data.
60
- - Keep tests resilient: isolate steps with subtests and clear assertions.
61
-
62
- ## Tool/Output Requirements
63
- - Default JSON output remains stable.
64
- - `--output ndjson` must stay stream-friendly and compatible with file-offload behavior.
65
- - Large responses should offload to temp files when `result-mode` is `auto|file`.
66
- - `batch` should default to token-efficient item payloads; full envelopes opt-in.
67
-
68
- ## Agent Action Gate
69
- - Mutating actions are gated by default and must be explicit:
70
- - pass `performAction: true` on mutation/delete operations.
71
- - Safe delete flow requires prior read confirmation:
72
- 1. Call `documents.info` with `armDelete: true` on target document(s).
73
- 2. Use returned `deleteReadReceipt.token` as `readToken` for delete.
74
- 3. Execute delete only with `performAction: true`.
75
- - Delete operations must fail if read token is missing, stale, mismatched, or expired.
76
-
77
- ## Security + Secrets
78
- - Never commit real Outline API keys or `.env.test.local`.
79
- - Secret scan guard test must pass.
80
- - If a key is exposed, rotate immediately and update local env.
81
-
82
- ## Deployment / Release
83
- - Pre-release checklist:
84
- 1. Ensure clean git working tree.
85
- 2. Ensure `OUTLINE_ENTRY_BUILD_KEY` is set (`.env.local` or env).
86
- 3. Ensure npm auth is ready (`npm login`).
87
- - Primary workflow command:
88
- - `npm run release -- --bump patch`
89
- - or `npm run release -- --version X.Y.Z`
90
- - Prepare-only workflow (no publish/push):
91
- - `npm run release:prepare -- --bump patch`
92
- - Agent execution rule:
93
- - If user asks to "deploy" or "release", run `npm run release -- --bump patch` by default unless user specifies a version/tag strategy.
94
- - Release script responsibilities (`scripts/release.mjs`):
95
- - version bump (`npm version --no-git-tag-version`)
96
- - changelog update (`CHANGELOG.md`)
97
- - integrity refresh (`npm run integrity:refresh`)
98
- - verification (`npm run check`, `npm test`)
99
- - packaging validation (`npm pack --dry-run`)
100
- - git commit + tag (`chore(release): vX.Y.Z`, `vX.Y.Z`)
101
- - npm publish (`--access public`) and git push to `origin`
102
-
103
- ## Temporary Knowledge Notes
104
- Use local scratch references under:
105
- - `/tmp/knowledges/*.md`
106
-
107
- These are intentionally ignored by git and can store short-lived research/decision notes.