@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.
- package/CHANGELOG.md +10 -0
- package/README.md +22 -0
- package/package.json +7 -1
- package/src/agent-skills.js +45 -2
- package/src/entry-integrity-manifest.generated.js +6 -6
- package/src/outline-client.js +93 -0
- package/src/tool-arg-schemas.js +55 -0
- package/src/tools.extended.js +377 -12
- package/.env.test.example +0 -2
- package/AGENTS.md +0 -107
- package/docs/TOOL_CONTRACTS.md +0 -8
- package/scripts/generate-entry-integrity.mjs +0 -123
- package/scripts/release.mjs +0 -353
- package/test/action-gate.unit.test.js +0 -157
- package/test/agent-skills.unit.test.js +0 -144
- package/test/config-store.unit.test.js +0 -121
- package/test/hardening.unit.test.js +0 -3803
- package/test/live.integration.test.js +0 -5136
- package/test/profile-selection.unit.test.js +0 -289
- package/test/security.unit.test.js +0 -113
- package/test/tool-resolution.unit.test.js +0 -333
- package/test/version.unit.test.js +0 -21
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.7 - 2026-06-10
|
|
4
|
+
|
|
5
|
+
- Changes since `v0.1.6`.
|
|
6
|
+
- feat: add Outline attachment downloads (e7d3ec0)
|
|
7
|
+
|
|
8
|
+
## 0.1.6 - 2026-03-08
|
|
9
|
+
|
|
10
|
+
- Changes since `v0.1.5`.
|
|
11
|
+
- build(npm): whitelist published files (b2838fa)
|
|
12
|
+
|
|
3
13
|
## 0.1.5 - 2026-03-08
|
|
4
14
|
|
|
5
15
|
- Changes since `v0.1.4`.
|
package/README.md
CHANGED
|
@@ -42,6 +42,19 @@ outline-cli invoke documents.info \
|
|
|
42
42
|
--args '{"id":"<document-id>","view":"summary"}'
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
+
List and save embedded document images/files:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
outline-cli invoke documents.attachments \
|
|
49
|
+
--args '{"url":"https://handbook.example.com/doc/example-title-AbCdEf1234"}'
|
|
50
|
+
|
|
51
|
+
outline-cli invoke documents.download_attachments \
|
|
52
|
+
--args '{"url":"https://handbook.example.com/doc/example-title-AbCdEf1234","outputDir":"./outline-attachments","overwrite":true}'
|
|
53
|
+
|
|
54
|
+
outline-cli invoke attachments.download \
|
|
55
|
+
--args '{"id":"<attachment-id>","outputDir":"./outline-attachments","overwrite":true}'
|
|
56
|
+
```
|
|
57
|
+
|
|
45
58
|
List only collection root pages:
|
|
46
59
|
|
|
47
60
|
```bash
|
|
@@ -163,6 +176,7 @@ Use this short operating pattern when an AI agent drives the CLI:
|
|
|
163
176
|
9. List existing profiles before creating one with `outline-cli profile list`.
|
|
164
177
|
10. For new profiles, prefer API key mode and guide users through base URL + API key generation (`<base-url>/settings/api-and-apps`) before `profile add`.
|
|
165
178
|
11. If output is file-offloaded, read only the required fields via `tmp cat` + `jq`.
|
|
179
|
+
12. For embedded images/files in document markdown, use `documents.attachments`, `attachments.download`, or `documents.download_attachments`; do not force `attachments.redirect` through `api.call` because it returns binary data.
|
|
166
180
|
|
|
167
181
|
For structured AI playbooks and scenario guides:
|
|
168
182
|
|
|
@@ -222,6 +236,14 @@ Release prerequisites:
|
|
|
222
236
|
- `OUTLINE_ENTRY_BUILD_KEY` available in environment or `.env.local`
|
|
223
237
|
- npm auth ready (`npm login`)
|
|
224
238
|
|
|
239
|
+
Optional GitHub automation:
|
|
240
|
+
|
|
241
|
+
- `.github/workflows/npm-auto-publish.yml` auto-publishes on pushes to `main` when `README.md` or `package.json` changes.
|
|
242
|
+
- If `package.json` version changes, the workflow publishes that exact version.
|
|
243
|
+
- If only docs metadata changes (for example `README.md`), the workflow cuts and publishes a patch release automatically.
|
|
244
|
+
- Required repository secrets: `NPM_TOKEN` and `OUTLINE_ENTRY_BUILD_KEY`.
|
|
245
|
+
- Ensure GitHub Actions can push to `main` and create tags in this repository.
|
|
246
|
+
|
|
225
247
|
## Security Notes
|
|
226
248
|
|
|
227
249
|
- Never commit real API keys.
|
package/package.json
CHANGED
|
@@ -1,12 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@khanglvm/outline-cli",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
4
4
|
"description": "Agent-optimized CLI for Outline API",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"outline-cli": "bin/outline-cli.js",
|
|
8
8
|
"outline-agent": "bin/outline-cli.js"
|
|
9
9
|
},
|
|
10
|
+
"files": [
|
|
11
|
+
"bin/",
|
|
12
|
+
"src/",
|
|
13
|
+
"README.md",
|
|
14
|
+
"CHANGELOG.md"
|
|
15
|
+
],
|
|
10
16
|
"scripts": {
|
|
11
17
|
"start": "node ./bin/outline-cli.js",
|
|
12
18
|
"check": "node ./bin/outline-cli.js --help",
|
package/src/agent-skills.js
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { CliError } from "./errors.js";
|
|
2
2
|
|
|
3
|
-
const AI_SKILL_DATA_VERSION = "2026-
|
|
3
|
+
const AI_SKILL_DATA_VERSION = "2026-06-10.1";
|
|
4
4
|
const AI_HELP_SECTION_ID = "ai-skills";
|
|
5
5
|
const QUICK_START_HELP_SECTION_ID = "quick-start-agent";
|
|
6
|
-
const QUICK_START_HELP_VERSION = "2026-
|
|
6
|
+
const QUICK_START_HELP_VERSION = "2026-06-10.1";
|
|
7
7
|
|
|
8
8
|
const QUICK_START_AGENT_PLAYBOOK = {
|
|
9
9
|
title: "outline-cli onboarding for non-expert users",
|
|
@@ -137,6 +137,7 @@ const QUICK_START_AGENT_PLAYBOOK = {
|
|
|
137
137
|
"Create a draft release notes document with today's date.",
|
|
138
138
|
"Append a short status update to document <document-id>.",
|
|
139
139
|
"Find documents mentioning incident response in the last month.",
|
|
140
|
+
"Download the embedded images from document <document-url> into ./outline-attachments.",
|
|
140
141
|
"Show who can access document <document-id>.",
|
|
141
142
|
"Compare two documents and list key differences.",
|
|
142
143
|
"Generate a TODO list from document <document-id>.",
|
|
@@ -172,6 +173,7 @@ const AI_GLOBAL_GUIDANCE = {
|
|
|
172
173
|
"Prefer batch operations (queries, ids, or batch command) before multi-call loops.",
|
|
173
174
|
"For heavy retrieval, use search.research with precisionMode + perQueryView/perQueryHitLimit to control token cost.",
|
|
174
175
|
"When outputs offload to tmp files, read the new preview first, then inspect file content only when needed.",
|
|
176
|
+
"For embedded images/files, use documents.attachments or documents.download_attachments; attachments.redirect returns binary bytes and should not go through api.call.",
|
|
175
177
|
"Keep mutating calls action-gated and explicit with performAction=true only at execute time.",
|
|
176
178
|
"Capture audit evidence (events/revisions/policies) immediately after high-impact changes.",
|
|
177
179
|
],
|
|
@@ -360,6 +362,47 @@ const AI_SKILLS = [
|
|
|
360
362
|
"Never apply mutation from synthetic issue refs without doc hydration.",
|
|
361
363
|
],
|
|
362
364
|
},
|
|
365
|
+
{
|
|
366
|
+
id: "embedded_attachment_access",
|
|
367
|
+
title: "Embedded attachment and image access",
|
|
368
|
+
scenarios: ["UC-08", "UC-12"],
|
|
369
|
+
objective: "Extract, download, and hand off files embedded in Outline documents, including markdown images.",
|
|
370
|
+
featureUpdates: [
|
|
371
|
+
"documents.attachments extracts /api/attachments.redirect references from document markdown.",
|
|
372
|
+
"attachments.download and documents.download_attachments save authenticated binary attachment bytes locally with contentType, byte count, and sha256 metadata.",
|
|
373
|
+
],
|
|
374
|
+
sequence: [
|
|
375
|
+
{
|
|
376
|
+
step: 1,
|
|
377
|
+
tool: "documents.attachments",
|
|
378
|
+
purpose: "List embedded attachment IDs and source URLs without downloading bytes.",
|
|
379
|
+
},
|
|
380
|
+
{
|
|
381
|
+
step: 2,
|
|
382
|
+
tool: "attachments.download",
|
|
383
|
+
purpose: "Save one selected attachment/image to a local file.",
|
|
384
|
+
},
|
|
385
|
+
{
|
|
386
|
+
step: 3,
|
|
387
|
+
tool: "documents.download_attachments",
|
|
388
|
+
purpose: "Save every embedded file from a document into an output directory.",
|
|
389
|
+
},
|
|
390
|
+
{
|
|
391
|
+
step: 4,
|
|
392
|
+
tool: "documents.info",
|
|
393
|
+
purpose: "Re-read the document only when you need surrounding text context for downloaded files.",
|
|
394
|
+
},
|
|
395
|
+
],
|
|
396
|
+
efficiencyTips: [
|
|
397
|
+
"Run documents.attachments first when you only need IDs or want to choose a subset.",
|
|
398
|
+
"Use a scratch outputDir plus overwrite=true for repeatable automation.",
|
|
399
|
+
"Keep download concurrency modest for image-heavy documents.",
|
|
400
|
+
],
|
|
401
|
+
safetyChecks: [
|
|
402
|
+
"Do not use api.call for attachments.redirect; it is a binary endpoint.",
|
|
403
|
+
"Verify returned bytes, contentType, sha256, and filePath before downstream processing.",
|
|
404
|
+
],
|
|
405
|
+
},
|
|
363
406
|
{
|
|
364
407
|
id: "rollback_safe_editing",
|
|
365
408
|
title: "Rollback-safe postmortem editing",
|
|
@@ -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-
|
|
6
|
+
signature: "e811622c1740da1e9a0833e3a00451bbbbe14ad30b29400fd341484db589a301",
|
|
7
|
+
generatedAt: "2026-06-10T08:57:44.270Z",
|
|
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": "6a23db3378050f5a2e46564bca921985708fddbc144316efd39654d0f2860693"
|
|
16
16
|
},
|
|
17
17
|
{
|
|
18
18
|
"path": "src/cli.js",
|
|
@@ -32,7 +32,7 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
|
|
|
32
32
|
},
|
|
33
33
|
{
|
|
34
34
|
"path": "src/outline-client.js",
|
|
35
|
-
"sha256": "
|
|
35
|
+
"sha256": "457900dfee7c521f0683a0344009621df720e72d8cdcb3b32b4efed1c3fdf9be"
|
|
36
36
|
},
|
|
37
37
|
{
|
|
38
38
|
"path": "src/result-store.js",
|
|
@@ -48,11 +48,11 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
|
|
|
48
48
|
},
|
|
49
49
|
{
|
|
50
50
|
"path": "src/tool-arg-schemas.js",
|
|
51
|
-
"sha256": "
|
|
51
|
+
"sha256": "e1256642373a8b619b9b690be422e8d7d660e1f67bac10ff9ca237950df0b73d"
|
|
52
52
|
},
|
|
53
53
|
{
|
|
54
54
|
"path": "src/tools.extended.js",
|
|
55
|
-
"sha256": "
|
|
55
|
+
"sha256": "2861108ad0f2d42ad807f222f367557be3b2c6414a58006c89f9afe4bab85e22"
|
|
56
56
|
},
|
|
57
57
|
{
|
|
58
58
|
"path": "src/tools.js",
|
package/src/outline-client.js
CHANGED
|
@@ -39,6 +39,35 @@ export class OutlineClient {
|
|
|
39
39
|
throw lastErr;
|
|
40
40
|
}
|
|
41
41
|
|
|
42
|
+
async download(method, body = {}, options = {}) {
|
|
43
|
+
const apiMethod = method.startsWith("/") ? method.slice(1) : method;
|
|
44
|
+
const url = `${this.baseApiUrl}/${apiMethod}`;
|
|
45
|
+
const maxAttempts = Math.max(1, options.maxAttempts || 1);
|
|
46
|
+
|
|
47
|
+
let lastErr;
|
|
48
|
+
for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
|
|
49
|
+
try {
|
|
50
|
+
return await this.#downloadOnce(url, body, options);
|
|
51
|
+
} catch (err) {
|
|
52
|
+
lastErr = err;
|
|
53
|
+
const shouldRetry =
|
|
54
|
+
err instanceof ApiError &&
|
|
55
|
+
(err.details.status === 429 || err.details.status >= 500) &&
|
|
56
|
+
attempt < maxAttempts;
|
|
57
|
+
|
|
58
|
+
if (!shouldRetry) {
|
|
59
|
+
throw err;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const retryAfter = Number(err.details.retryAfter || 0);
|
|
63
|
+
const waitMs = retryAfter > 0 ? retryAfter * 1000 : attempt * 400;
|
|
64
|
+
await sleep(waitMs);
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
throw lastErr;
|
|
69
|
+
}
|
|
70
|
+
|
|
42
71
|
async #callOnce(url, body, options) {
|
|
43
72
|
const bodyType = options.bodyType === "multipart" ? "multipart" : "json";
|
|
44
73
|
const requestBody = this.#buildRequestBody(bodyType, body);
|
|
@@ -96,6 +125,70 @@ export class OutlineClient {
|
|
|
96
125
|
};
|
|
97
126
|
}
|
|
98
127
|
|
|
128
|
+
async #downloadOnce(url, body, options) {
|
|
129
|
+
const requestBody = this.#buildRequestBody(options.bodyType === "multipart" ? "multipart" : "json", body);
|
|
130
|
+
const headers = await this.#buildHeaders(
|
|
131
|
+
{
|
|
132
|
+
Accept: "*/*",
|
|
133
|
+
...(options.headers || {}),
|
|
134
|
+
},
|
|
135
|
+
{ bodyType: options.bodyType === "multipart" ? "multipart" : "json" }
|
|
136
|
+
);
|
|
137
|
+
const controller = new AbortController();
|
|
138
|
+
const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
|
|
139
|
+
|
|
140
|
+
let res;
|
|
141
|
+
try {
|
|
142
|
+
res = await fetch(url, {
|
|
143
|
+
method: "POST",
|
|
144
|
+
headers,
|
|
145
|
+
body: requestBody,
|
|
146
|
+
signal: controller.signal,
|
|
147
|
+
});
|
|
148
|
+
} catch (err) {
|
|
149
|
+
if (err.name === "AbortError") {
|
|
150
|
+
throw new ApiError(`Request timeout after ${this.timeoutMs}ms`, {
|
|
151
|
+
status: 408,
|
|
152
|
+
url,
|
|
153
|
+
});
|
|
154
|
+
}
|
|
155
|
+
throw new ApiError(`Network error: ${err.message}`, {
|
|
156
|
+
status: 503,
|
|
157
|
+
url,
|
|
158
|
+
});
|
|
159
|
+
} finally {
|
|
160
|
+
clearTimeout(timeout);
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
if (!res.ok) {
|
|
164
|
+
const text = await res.text().catch(() => "");
|
|
165
|
+
let parsed;
|
|
166
|
+
try {
|
|
167
|
+
parsed = text ? JSON.parse(text) : {};
|
|
168
|
+
} catch {
|
|
169
|
+
parsed = { ok: false, message: text || res.statusText };
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
const status = parsed?.status || res.status;
|
|
173
|
+
const retryAfter = res.headers.get("retry-after");
|
|
174
|
+
throw new ApiError(parsed?.message || parsed?.error || res.statusText, {
|
|
175
|
+
status,
|
|
176
|
+
retryAfter,
|
|
177
|
+
body: parsed,
|
|
178
|
+
url,
|
|
179
|
+
});
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
const buffer = Buffer.from(await res.arrayBuffer());
|
|
183
|
+
return {
|
|
184
|
+
ok: true,
|
|
185
|
+
status: res.status,
|
|
186
|
+
headers: Object.fromEntries(res.headers.entries()),
|
|
187
|
+
body: buffer,
|
|
188
|
+
url: res.url,
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
|
|
99
192
|
#buildRequestBody(bodyType, body) {
|
|
100
193
|
if (bodyType === "multipart") {
|
|
101
194
|
if (body instanceof FormData) {
|
package/src/tool-arg-schemas.js
CHANGED
|
@@ -640,6 +640,61 @@ export const TOOL_ARG_SCHEMAS = {
|
|
|
640
640
|
}
|
|
641
641
|
},
|
|
642
642
|
},
|
|
643
|
+
"documents.attachments": {
|
|
644
|
+
properties: {
|
|
645
|
+
id: { type: "string" },
|
|
646
|
+
documentId: { type: "string" },
|
|
647
|
+
url: { type: "string" },
|
|
648
|
+
shareId: { type: "string" },
|
|
649
|
+
maxAttempts: { type: "number", min: 1 },
|
|
650
|
+
},
|
|
651
|
+
custom(args, issues) {
|
|
652
|
+
if (!args.id && !args.documentId && !args.url && !args.shareId) {
|
|
653
|
+
issues.push({ path: "args.id", message: "or args.documentId, args.url, or args.shareId is required" });
|
|
654
|
+
}
|
|
655
|
+
},
|
|
656
|
+
},
|
|
657
|
+
"attachments.download": {
|
|
658
|
+
properties: {
|
|
659
|
+
id: { type: "string" },
|
|
660
|
+
attachmentId: { type: "string" },
|
|
661
|
+
url: { type: "string" },
|
|
662
|
+
path: { type: "string" },
|
|
663
|
+
outputDir: { type: "string" },
|
|
664
|
+
filePath: { type: "string" },
|
|
665
|
+
fileName: { type: "string" },
|
|
666
|
+
overwrite: { type: "boolean" },
|
|
667
|
+
maxAttempts: { type: "number", min: 1 },
|
|
668
|
+
},
|
|
669
|
+
custom(args, issues) {
|
|
670
|
+
if (!args.id && !args.attachmentId && !args.url && !args.path) {
|
|
671
|
+
issues.push({ path: "args.id", message: "or args.attachmentId, args.url, or args.path is required" });
|
|
672
|
+
}
|
|
673
|
+
if (args.filePath && (args.outputDir || args.fileName)) {
|
|
674
|
+
issues.push({ path: "args.filePath", message: "cannot be combined with args.outputDir or args.fileName" });
|
|
675
|
+
}
|
|
676
|
+
},
|
|
677
|
+
},
|
|
678
|
+
"documents.download_attachments": {
|
|
679
|
+
properties: {
|
|
680
|
+
id: { type: "string" },
|
|
681
|
+
documentId: { type: "string" },
|
|
682
|
+
url: { type: "string" },
|
|
683
|
+
shareId: { type: "string" },
|
|
684
|
+
outputDir: { type: "string" },
|
|
685
|
+
overwrite: { type: "boolean" },
|
|
686
|
+
concurrency: { type: "number", min: 1 },
|
|
687
|
+
maxAttempts: { type: "number", min: 1 },
|
|
688
|
+
},
|
|
689
|
+
custom(args, issues) {
|
|
690
|
+
if (!args.id && !args.documentId && !args.url && !args.shareId) {
|
|
691
|
+
issues.push({ path: "args.id", message: "or args.documentId, args.url, or args.shareId is required" });
|
|
692
|
+
}
|
|
693
|
+
if (typeof args.concurrency === "number" && args.concurrency > 8) {
|
|
694
|
+
issues.push({ path: "args.concurrency", message: "must be <= 8" });
|
|
695
|
+
}
|
|
696
|
+
},
|
|
697
|
+
},
|
|
643
698
|
"documents.info": {
|
|
644
699
|
properties: {
|
|
645
700
|
id: { type: "string" },
|