@solidactions/cli 1.28.0 → 1.30.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/README.md +35 -2
- package/dist/commands/crew-env-delete.js +50 -0
- package/dist/commands/crew-env-list.js +78 -0
- package/dist/commands/crew-env-push.js +162 -0
- package/dist/commands/crew-env-set.js +78 -0
- package/dist/commands/dev.js +39 -10
- package/dist/commands/docs-pull.js +570 -0
- package/dist/commands/docs-push.js +247 -8
- package/dist/commands/docs-upload.js +182 -0
- package/dist/commands/skill-exec.js +61 -0
- package/dist/commands/skill-pull.js +12 -0
- package/dist/commands/skill-push.js +88 -4
- package/dist/commands/skill-run.js +164 -0
- package/dist/index.js +97 -1
- package/dist/utils/crew.js +72 -0
- package/dist/utils/docs-manifest.js +48 -0
- package/package.json +1 -1
|
@@ -0,0 +1,570 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* solidactions docs pull <folder> [dest]
|
|
4
|
+
*
|
|
5
|
+
* Downloads a Docs folder tree from SA-Docs into a local markdown tree (the
|
|
6
|
+
* inverse of `docs push`): BFS-walks the folder via `docs_vault list`,
|
|
7
|
+
* bulk-fetches doc bodies via `docs_vault bulk_read`, and writes each doc as
|
|
8
|
+
* <dest>/<relative-folder>/<sanitized-title>.md plus a revision manifest
|
|
9
|
+
* (<dest>/.solidactions-docs.json) recording id/title/current_revision_id
|
|
10
|
+
* per file for later diffing.
|
|
11
|
+
*
|
|
12
|
+
* Media docs (blob-backed, empty body) are two-stage classified: a
|
|
13
|
+
* candidate filter on the bulk_read row's properties, then an authoritative
|
|
14
|
+
* confirm against `GET /api/v1/docs/{id}/media` — a 404 `media_not_found`
|
|
15
|
+
* means the candidate was a false positive and it's written as markdown
|
|
16
|
+
* like any other doc.
|
|
17
|
+
*/
|
|
18
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
19
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
20
|
+
};
|
|
21
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
22
|
+
exports.sha256Hex = exports.DOCS_MANIFEST = void 0;
|
|
23
|
+
exports.sanitizeSegment = sanitizeSegment;
|
|
24
|
+
exports.sanitizeTitle = sanitizeTitle;
|
|
25
|
+
exports.docsPullWithConfig = docsPullWithConfig;
|
|
26
|
+
exports.docsPull = docsPull;
|
|
27
|
+
const fs_1 = __importDefault(require("fs"));
|
|
28
|
+
const path_1 = __importDefault(require("path"));
|
|
29
|
+
const axios_1 = __importDefault(require("axios"));
|
|
30
|
+
const chalk_1 = __importDefault(require("chalk"));
|
|
31
|
+
const prompts_1 = __importDefault(require("prompts"));
|
|
32
|
+
const api_1 = require("../utils/api");
|
|
33
|
+
const mcp_1 = require("../utils/mcp");
|
|
34
|
+
const docs_manifest_1 = require("../utils/docs-manifest");
|
|
35
|
+
Object.defineProperty(exports, "DOCS_MANIFEST", { enumerable: true, get: function () { return docs_manifest_1.DOCS_MANIFEST; } });
|
|
36
|
+
Object.defineProperty(exports, "sha256Hex", { enumerable: true, get: function () { return docs_manifest_1.sha256Hex; } });
|
|
37
|
+
/** Extension appended to a media file's sanitized title when the title itself has none. */
|
|
38
|
+
const MIME_EXTENSIONS = {
|
|
39
|
+
'image/png': '.png',
|
|
40
|
+
'image/jpeg': '.jpg',
|
|
41
|
+
'image/gif': '.gif',
|
|
42
|
+
'image/webp': '.webp',
|
|
43
|
+
'application/pdf': '.pdf',
|
|
44
|
+
};
|
|
45
|
+
const CHUNK_SIZE = 50;
|
|
46
|
+
/** Characters that are unsafe as filesystem path segments, plus control chars. */
|
|
47
|
+
// eslint-disable-next-line no-control-regex
|
|
48
|
+
const UNSAFE_CHARS = /[/\\:*?"<>|\x00-\x1f]/g;
|
|
49
|
+
/**
|
|
50
|
+
* Replace filesystem-unsafe characters (/ \ : * ? " < > | and control chars)
|
|
51
|
+
* with underscores so a server-provided name (doc title or folder name) is
|
|
52
|
+
* safe to use as a single filesystem path segment. Also neutralizes bare
|
|
53
|
+
* `.` and `..` segments (which would otherwise resolve to the current or
|
|
54
|
+
* parent directory — a path-traversal risk for folder names in particular).
|
|
55
|
+
*/
|
|
56
|
+
function sanitizeSegment(name) {
|
|
57
|
+
const replaced = name.replace(UNSAFE_CHARS, '_');
|
|
58
|
+
if (replaced === '.')
|
|
59
|
+
return '_';
|
|
60
|
+
if (replaced === '..')
|
|
61
|
+
return '__';
|
|
62
|
+
return replaced;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Replace filesystem-unsafe characters (/ \ : * ? " < > | and control chars)
|
|
66
|
+
* in a doc title with underscores so it can be used as a file basename.
|
|
67
|
+
*/
|
|
68
|
+
function sanitizeTitle(title) {
|
|
69
|
+
return sanitizeSegment(title);
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* A doc is a media *candidate* when the bulk_read row carries blob metadata
|
|
73
|
+
* and an empty body. This is a cheap pre-filter, not authoritative — the
|
|
74
|
+
* media endpoint confirm can still return a false positive (see
|
|
75
|
+
* `resolveMedia`).
|
|
76
|
+
*/
|
|
77
|
+
function isMediaCandidate(doc) {
|
|
78
|
+
const props = doc.properties;
|
|
79
|
+
return Boolean(props.blob_sha && props.mime && props.size) && doc.body === '';
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Authoritatively confirm a media candidate against `GET /api/v1/docs/{id}/media`
|
|
83
|
+
* and, if confirmed, download the returned signed URL (no auth headers — it's
|
|
84
|
+
* a pre-signed R2 URL). Returns `{ isMedia: false }` for the false-positive
|
|
85
|
+
* 404 `media_not_found` case, in which the caller falls back to the D1
|
|
86
|
+
* markdown write path.
|
|
87
|
+
*/
|
|
88
|
+
async function resolveMedia(config, doc) {
|
|
89
|
+
const confirm = await axios_1.default.get(`${config.host}/api/v1/docs/${doc.id}/media`, {
|
|
90
|
+
headers: (0, api_1.getApiHeaders)(config),
|
|
91
|
+
validateStatus: () => true,
|
|
92
|
+
});
|
|
93
|
+
if (confirm.status === 404 && confirm.data?.code === 'media_not_found') {
|
|
94
|
+
return { isMedia: false };
|
|
95
|
+
}
|
|
96
|
+
if (confirm.status !== 200) {
|
|
97
|
+
const code = confirm.data?.code ?? 'unknown_error';
|
|
98
|
+
const message = confirm.data?.message ?? 'media confirm request failed';
|
|
99
|
+
process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
|
|
100
|
+
process.exit(1);
|
|
101
|
+
}
|
|
102
|
+
const { url, mime } = confirm.data;
|
|
103
|
+
const download = await axios_1.default.get(url, { responseType: 'arraybuffer', validateStatus: () => true });
|
|
104
|
+
if (download.status !== 200) {
|
|
105
|
+
return { isMedia: true, mime, bytes: null, warning: `warn: failed to download media for doc ${doc.id} (${doc.title}): HTTP ${download.status}` };
|
|
106
|
+
}
|
|
107
|
+
return { isMedia: true, mime, bytes: Buffer.from(download.data) };
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Compare each manifest-tracked file against its recorded `body_sha256` to
|
|
111
|
+
* find unpushed local edits. An entry without a hash (old manifest) or whose
|
|
112
|
+
* file is missing locally is never reported as modified — graceful
|
|
113
|
+
* degradation to "no detection" rather than a false refusal.
|
|
114
|
+
*/
|
|
115
|
+
function detectLocalModifications(destination, manifest) {
|
|
116
|
+
const modified = [];
|
|
117
|
+
for (const [relPath, entry] of Object.entries(manifest.docs)) {
|
|
118
|
+
if (entry.body_sha256 == null)
|
|
119
|
+
continue;
|
|
120
|
+
const absPath = path_1.default.join(destination, relPath);
|
|
121
|
+
// Only hash regular files. A corrupt manifest key naming a directory would
|
|
122
|
+
// otherwise throw EISDIR and abort the pull before it starts.
|
|
123
|
+
let stat;
|
|
124
|
+
try {
|
|
125
|
+
stat = fs_1.default.statSync(absPath);
|
|
126
|
+
}
|
|
127
|
+
catch {
|
|
128
|
+
continue; // missing locally — graceful degradation, never a false refusal
|
|
129
|
+
}
|
|
130
|
+
if (!stat.isFile())
|
|
131
|
+
continue;
|
|
132
|
+
const currentHash = (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(absPath));
|
|
133
|
+
if (currentHash !== entry.body_sha256) {
|
|
134
|
+
modified.push(relPath);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
return modified;
|
|
138
|
+
}
|
|
139
|
+
/** The last non-empty path segment of a '/'-separated folder path. */
|
|
140
|
+
function lastSegment(folderPath) {
|
|
141
|
+
const segments = folderPath.split('/').filter(Boolean);
|
|
142
|
+
return segments[segments.length - 1] ?? folderPath;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* BFS-walk `folderPath` via `docs_vault list`, collecting every doc row with
|
|
146
|
+
* its relative folder path. Returns null (with the list error message
|
|
147
|
+
* already known to the caller) if the root list call fails.
|
|
148
|
+
*/
|
|
149
|
+
async function listTree(config, folderPath) {
|
|
150
|
+
const rows = [];
|
|
151
|
+
const queue = [{ folder_path: folderPath, relative: '' }];
|
|
152
|
+
let first = true;
|
|
153
|
+
while (queue.length > 0) {
|
|
154
|
+
const { folder_path, relative } = queue.shift();
|
|
155
|
+
const result = await (0, mcp_1.callDocsTool)(config, 'docs_vault', { action: 'list', folder_path });
|
|
156
|
+
if (!result.ok) {
|
|
157
|
+
// A subfolder returned by the server itself failed to list is surfaced the
|
|
158
|
+
// same way as a root failure — only the root failure triggers the
|
|
159
|
+
// single-doc fallback (isRoot distinguishes the two).
|
|
160
|
+
return { ok: false, isRoot: first, code: result.data?.code ?? 'unknown_error', message: result.data?.message ?? 'MCP returned an error with no message' };
|
|
161
|
+
}
|
|
162
|
+
first = false;
|
|
163
|
+
for (const folder of result.data?.folders ?? []) {
|
|
164
|
+
const safeName = sanitizeSegment(folder.name);
|
|
165
|
+
const childRelative = relative ? `${relative}/${safeName}` : safeName;
|
|
166
|
+
queue.push({ folder_path: folder.folder_path, relative: childRelative });
|
|
167
|
+
}
|
|
168
|
+
for (const doc of result.data?.docs ?? []) {
|
|
169
|
+
rows.push({ id: doc.id, title: doc.title, relative });
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
return { ok: true, rows };
|
|
173
|
+
}
|
|
174
|
+
/** The bulk_read row status that means "body/revision were returned successfully". */
|
|
175
|
+
const BULK_READ_OK_STATUS = 'found';
|
|
176
|
+
/**
|
|
177
|
+
* Fetch bodies + revisions for every collected row via bulk_read, chunked at
|
|
178
|
+
* CHUNK_SIZE ids. A row whose status isn't `BULK_READ_OK_STATUS` (e.g. a
|
|
179
|
+
* server-side `error` or `not_found`), or a requested id absent from the
|
|
180
|
+
* response entirely, is soft-skipped: a warning naming the doc, no file
|
|
181
|
+
* written, no manifest entry — mirroring the media download soft-skip.
|
|
182
|
+
*/
|
|
183
|
+
async function fetchBodies(config, rows) {
|
|
184
|
+
const byId = new Map();
|
|
185
|
+
for (const row of rows)
|
|
186
|
+
byId.set(row.id, row);
|
|
187
|
+
const fetched = [];
|
|
188
|
+
const warnings = [];
|
|
189
|
+
for (let i = 0; i < rows.length; i += CHUNK_SIZE) {
|
|
190
|
+
const chunk = rows.slice(i, i + CHUNK_SIZE);
|
|
191
|
+
const result = await (0, mcp_1.callDocsTool)(config, 'docs_vault', {
|
|
192
|
+
action: 'bulk_read',
|
|
193
|
+
items: chunk.map((r) => ({ id: r.id })),
|
|
194
|
+
});
|
|
195
|
+
if (!result.ok) {
|
|
196
|
+
const code = result.data?.code ?? 'unknown_error';
|
|
197
|
+
const message = result.data?.message ?? 'MCP returned an error with no message';
|
|
198
|
+
process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
|
|
199
|
+
process.exit(1);
|
|
200
|
+
}
|
|
201
|
+
const resultRows = result.data?.results ?? [];
|
|
202
|
+
const seenIds = new Set();
|
|
203
|
+
for (const row of resultRows) {
|
|
204
|
+
const original = byId.get(row.id);
|
|
205
|
+
if (!original)
|
|
206
|
+
continue;
|
|
207
|
+
seenIds.add(row.id);
|
|
208
|
+
if (row.status !== BULK_READ_OK_STATUS) {
|
|
209
|
+
warnings.push(`warn: skipping doc ${row.id} (${original.title}): bulk_read returned status "${row.status ?? 'unknown'}"`);
|
|
210
|
+
continue;
|
|
211
|
+
}
|
|
212
|
+
fetched.push({
|
|
213
|
+
...original,
|
|
214
|
+
body: row.body ?? '',
|
|
215
|
+
current_revision_id: row.current_revision_id ?? null,
|
|
216
|
+
properties: row.properties ?? {},
|
|
217
|
+
});
|
|
218
|
+
}
|
|
219
|
+
for (const requested of chunk) {
|
|
220
|
+
if (!seenIds.has(requested.id)) {
|
|
221
|
+
warnings.push(`warn: skipping doc ${requested.id} (${requested.title}): missing from bulk_read results`);
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
return { fetched, warnings };
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Resolve every fetched doc into a `PlannedDoc` — final relative path and
|
|
229
|
+
* content hash — confirming/downloading media as needed. This is the only
|
|
230
|
+
* place that talks to the media confirm/download endpoints; it performs no
|
|
231
|
+
* filesystem writes.
|
|
232
|
+
*/
|
|
233
|
+
async function planDocs(docs, config) {
|
|
234
|
+
const planned = [];
|
|
235
|
+
const warnings = [];
|
|
236
|
+
const usedNamesByDir = new Map();
|
|
237
|
+
for (const doc of docs) {
|
|
238
|
+
const dirRel = doc.relative;
|
|
239
|
+
let used = usedNamesByDir.get(dirRel);
|
|
240
|
+
if (!used) {
|
|
241
|
+
used = new Set();
|
|
242
|
+
usedNamesByDir.set(dirRel, used);
|
|
243
|
+
}
|
|
244
|
+
const media = isMediaCandidate(doc) ? await resolveMedia(config, doc) : { isMedia: false };
|
|
245
|
+
if (media.warning)
|
|
246
|
+
warnings.push(media.warning);
|
|
247
|
+
const sanitized = sanitizeTitle(doc.title);
|
|
248
|
+
let base = sanitized;
|
|
249
|
+
let ext = '.md';
|
|
250
|
+
if (media.isMedia) {
|
|
251
|
+
const titleExt = path_1.default.extname(sanitized);
|
|
252
|
+
if (titleExt) {
|
|
253
|
+
base = sanitized.slice(0, -titleExt.length);
|
|
254
|
+
ext = titleExt;
|
|
255
|
+
}
|
|
256
|
+
else {
|
|
257
|
+
base = sanitized;
|
|
258
|
+
ext = (media.mime && MIME_EXTENSIONS[media.mime]) ?? '';
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
let candidate = base;
|
|
262
|
+
let suffix = 2;
|
|
263
|
+
while (used.has(`${candidate}${ext}`)) {
|
|
264
|
+
candidate = `${base}-${suffix}`;
|
|
265
|
+
suffix++;
|
|
266
|
+
}
|
|
267
|
+
used.add(`${candidate}${ext}`);
|
|
268
|
+
const fileName = `${candidate}${ext}`;
|
|
269
|
+
const relPath = dirRel ? `${dirRel}/${fileName}` : fileName;
|
|
270
|
+
let bodySha256;
|
|
271
|
+
let mediaBytes = null;
|
|
272
|
+
if (media.isMedia) {
|
|
273
|
+
if (media.bytes) {
|
|
274
|
+
mediaBytes = media.bytes;
|
|
275
|
+
bodySha256 = (0, docs_manifest_1.sha256Hex)(media.bytes);
|
|
276
|
+
}
|
|
277
|
+
else {
|
|
278
|
+
// Download failure: warning already recorded above; the doc is still
|
|
279
|
+
// tracked (manifest entry written by commitDocs) but there is nothing
|
|
280
|
+
// to write to disk.
|
|
281
|
+
bodySha256 = null;
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
else {
|
|
285
|
+
bodySha256 = (0, docs_manifest_1.sha256Hex)(doc.body);
|
|
286
|
+
}
|
|
287
|
+
planned.push({ doc, relPath, dirRel, fileName, isMedia: media.isMedia, mediaBytes, bodySha256 });
|
|
288
|
+
}
|
|
289
|
+
return { planned, warnings };
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* Write every planned doc to disk under `destination` and build the
|
|
293
|
+
* manifest docs map. The only step in the whole pull that creates
|
|
294
|
+
* directories or writes/overwrites files — called only after any
|
|
295
|
+
* unpushed-local-changes conflict has already refused, so it never clobbers
|
|
296
|
+
* a file the caller decided to keep.
|
|
297
|
+
*/
|
|
298
|
+
function commitDocs(destination, planned) {
|
|
299
|
+
const manifestDocs = {};
|
|
300
|
+
const files = [];
|
|
301
|
+
for (const p of planned) {
|
|
302
|
+
const dirAbs = p.dirRel ? path_1.default.join(destination, ...p.dirRel.split('/')) : destination;
|
|
303
|
+
fs_1.default.mkdirSync(dirAbs, { recursive: true });
|
|
304
|
+
// A destination path that already exists as a directory would make writeFileSync
|
|
305
|
+
// throw EISDIR mid-walk, after earlier docs were written and before the manifest
|
|
306
|
+
// is saved — a half-pulled tree with a stale sidecar. Fail cleanly instead.
|
|
307
|
+
const targetAbs = path_1.default.join(dirAbs, p.fileName);
|
|
308
|
+
if (fs_1.default.existsSync(targetAbs) && !fs_1.default.statSync(targetAbs).isFile()) {
|
|
309
|
+
process.stderr.write(chalk_1.default.red(`error: "${p.relPath}" exists and is not a regular file — cannot write doc ${p.doc.id} (${p.doc.title}).\n`));
|
|
310
|
+
process.exit(1);
|
|
311
|
+
}
|
|
312
|
+
if (p.isMedia) {
|
|
313
|
+
if (p.mediaBytes) {
|
|
314
|
+
fs_1.default.writeFileSync(targetAbs, p.mediaBytes);
|
|
315
|
+
files.push({ path: p.relPath, action: 'written' });
|
|
316
|
+
}
|
|
317
|
+
// else: download failure, warning already recorded by planDocs; skip the
|
|
318
|
+
// write but still record the manifest entry below so the doc isn't lost.
|
|
319
|
+
}
|
|
320
|
+
else {
|
|
321
|
+
fs_1.default.writeFileSync(targetAbs, p.doc.body, 'utf8');
|
|
322
|
+
files.push({ path: p.relPath, action: 'written' });
|
|
323
|
+
}
|
|
324
|
+
manifestDocs[p.relPath] = {
|
|
325
|
+
id: p.doc.id,
|
|
326
|
+
title: p.doc.title,
|
|
327
|
+
current_revision_id: p.doc.current_revision_id,
|
|
328
|
+
media: p.isMedia,
|
|
329
|
+
body_sha256: p.bodySha256,
|
|
330
|
+
};
|
|
331
|
+
}
|
|
332
|
+
return { manifestDocs, files };
|
|
333
|
+
}
|
|
334
|
+
/**
|
|
335
|
+
* Core implementation — accepts an injected config so tests can point at a
|
|
336
|
+
* stub server without touching the filesystem config.
|
|
337
|
+
*/
|
|
338
|
+
async function docsPullWithConfig(folderPath, dest, options, config) {
|
|
339
|
+
const destInput = dest ?? `./${lastSegment(folderPath)}`;
|
|
340
|
+
const destination = path_1.default.resolve(destInput);
|
|
341
|
+
// Captured once, before the walk, so deletion propagation (below) can diff
|
|
342
|
+
// against the folder tree as it stood before this pull. Already read below
|
|
343
|
+
// for overwrite protection — hoisted here rather than read twice.
|
|
344
|
+
const previousManifest = fs_1.default.existsSync(destination) ? (0, docs_manifest_1.readManifest)(destination) : null;
|
|
345
|
+
let usedSingleDocFallback = false;
|
|
346
|
+
// Overwrite-confirm: warn + confirm on a non-empty destination before any network I/O.
|
|
347
|
+
// The unpushed-local-changes conflict refusal (detectLocalModifications) happens later,
|
|
348
|
+
// in report() — only once the server walk is known can it tell a real conflict (the
|
|
349
|
+
// doc still exists remotely) from an edited orphan (kept + warned, no flag needed).
|
|
350
|
+
if (fs_1.default.existsSync(destination)) {
|
|
351
|
+
if (!fs_1.default.statSync(destination).isDirectory()) {
|
|
352
|
+
process.stderr.write(chalk_1.default.red(`error: destination "${destination}" exists and is not a directory.\n`));
|
|
353
|
+
process.exit(1);
|
|
354
|
+
}
|
|
355
|
+
const entries = fs_1.default.readdirSync(destination);
|
|
356
|
+
if (entries.length > 0 && !options.yes && !options.overwrite) {
|
|
357
|
+
console.log(chalk_1.default.yellow(`Destination "${destination}" is not empty (${entries.length} items).`));
|
|
358
|
+
console.log(chalk_1.default.yellow('Pulling will overwrite existing files.'));
|
|
359
|
+
const response = await (0, prompts_1.default)({
|
|
360
|
+
type: 'confirm',
|
|
361
|
+
name: 'proceed',
|
|
362
|
+
message: 'Continue?',
|
|
363
|
+
initial: false,
|
|
364
|
+
});
|
|
365
|
+
if (!response.proceed) {
|
|
366
|
+
console.log(chalk_1.default.gray('Cancelled.'));
|
|
367
|
+
process.exit(0);
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
// Manifest-clobber protection: a manifest tracking a DIFFERENT folder than the one
|
|
372
|
+
// being pulled must never be silently replaced — every file it tracks would become
|
|
373
|
+
// untracked, and detectLocalModifications only protects tracked files. This must run
|
|
374
|
+
// before any network I/O (listTree/planDocs) and before detectLocalModifications, since
|
|
375
|
+
// a mismatched manifest can't meaningfully speak for the folder being pulled anyway.
|
|
376
|
+
// --overwrite already means "discard local-edit protection", so it bypasses this too.
|
|
377
|
+
if (previousManifest !== null && previousManifest.folder_path !== folderPath && !options.overwrite) {
|
|
378
|
+
process.stderr.write(chalk_1.default.red(`error: "${destination}" already tracks "${previousManifest.folder_path}".\n`));
|
|
379
|
+
process.stderr.write(chalk_1.default.red(`Pulling "${folderPath}" here would replace its manifest, and local edits to the\n`));
|
|
380
|
+
process.stderr.write(chalk_1.default.red('previously tracked files would no longer be protected from being overwritten.\n'));
|
|
381
|
+
process.stderr.write(chalk_1.default.red('Pull into a different directory, or pass --overwrite to replace the manifest.\n'));
|
|
382
|
+
process.exit(1);
|
|
383
|
+
}
|
|
384
|
+
let rows;
|
|
385
|
+
const listResult = await listTree(config, folderPath);
|
|
386
|
+
if (listResult.ok) {
|
|
387
|
+
rows = listResult.rows;
|
|
388
|
+
}
|
|
389
|
+
else if (listResult.isRoot && listResult.code === 'folder_path_not_found') {
|
|
390
|
+
// Single-doc fallback: the target might be a doc path, not a folder.
|
|
391
|
+
usedSingleDocFallback = true;
|
|
392
|
+
const dir = path_1.default.dirname(folderPath);
|
|
393
|
+
const title = path_1.default.basename(folderPath);
|
|
394
|
+
const readArgs = { action: 'read', path: dir === '.' ? { title } : { folder_path: dir, title } };
|
|
395
|
+
const readResult = await (0, mcp_1.callDocsTool)(config, 'docs_vault', readArgs);
|
|
396
|
+
if (!readResult.ok) {
|
|
397
|
+
const readCode = readResult.data?.code ?? 'unknown_error';
|
|
398
|
+
const readMessage = readResult.data?.message ?? 'MCP returned an error with no message';
|
|
399
|
+
process.stderr.write(chalk_1.default.red(`error: ${listResult.code}: ${listResult.message}\n`));
|
|
400
|
+
process.stderr.write(chalk_1.default.red(`error: ${readCode}: ${readMessage}\n`));
|
|
401
|
+
process.exit(1);
|
|
402
|
+
}
|
|
403
|
+
const data = readResult.data;
|
|
404
|
+
const fetched = [{
|
|
405
|
+
id: data.id,
|
|
406
|
+
title: data.title,
|
|
407
|
+
relative: '',
|
|
408
|
+
body: data.body ?? '',
|
|
409
|
+
current_revision_id: data.current_revision_id ?? null,
|
|
410
|
+
properties: data.properties ?? {},
|
|
411
|
+
}];
|
|
412
|
+
await report(destination, folderPath, fetched, options, config, [], previousManifest, usedSingleDocFallback);
|
|
413
|
+
return;
|
|
414
|
+
}
|
|
415
|
+
else {
|
|
416
|
+
process.stderr.write(chalk_1.default.red(`error: ${listResult.code}: ${listResult.message}\n`));
|
|
417
|
+
process.exit(1);
|
|
418
|
+
return;
|
|
419
|
+
}
|
|
420
|
+
const { fetched, warnings: fetchWarnings } = await fetchBodies(config, rows);
|
|
421
|
+
await report(destination, folderPath, fetched, options, config, fetchWarnings, previousManifest, usedSingleDocFallback);
|
|
422
|
+
}
|
|
423
|
+
/** Write the docs + manifest to disk and print the result (chalk lines or --json). */
|
|
424
|
+
async function report(destination, folderPath, fetched, options, config, extraWarnings, previousManifest, usedSingleDocFallback) {
|
|
425
|
+
const { planned, warnings } = await planDocs(fetched, config);
|
|
426
|
+
// Unpushed-local-changes protection: now that the server walk is known, refuse only
|
|
427
|
+
// for a file whose doc still exists remotely — i.e. its relative path is part of this
|
|
428
|
+
// pull's plan and would be overwritten by commitDocs below. A modified file whose
|
|
429
|
+
// relPath is NOT in the plan is an orphan, not a conflict: it is left alone here and
|
|
430
|
+
// the deletion-propagation block further down keeps it and warns (no --overwrite
|
|
431
|
+
// needed). This check must run before commitDocs — nothing may be written to disk
|
|
432
|
+
// before a real conflict has had the chance to refuse.
|
|
433
|
+
if (previousManifest && !options.overwrite) {
|
|
434
|
+
const modified = detectLocalModifications(destination, previousManifest);
|
|
435
|
+
const plannedPaths = new Set(planned.map((p) => p.relPath));
|
|
436
|
+
const conflicts = modified.filter((relPath) => plannedPaths.has(relPath));
|
|
437
|
+
if (conflicts.length > 0) {
|
|
438
|
+
const noun = conflicts.length === 1 ? 'file has' : 'files have';
|
|
439
|
+
process.stderr.write(chalk_1.default.red(`${conflicts.length} ${noun} unpushed local changes:\n`));
|
|
440
|
+
for (const file of conflicts) {
|
|
441
|
+
process.stderr.write(chalk_1.default.red(` ${file}\n`));
|
|
442
|
+
}
|
|
443
|
+
process.stderr.write(chalk_1.default.red('push your changes first, or pass --overwrite to discard them.\n'));
|
|
444
|
+
process.exit(1);
|
|
445
|
+
}
|
|
446
|
+
}
|
|
447
|
+
fs_1.default.mkdirSync(destination, { recursive: true });
|
|
448
|
+
const { manifestDocs, files } = commitDocs(destination, planned);
|
|
449
|
+
// Identity of every file this pull actually wrote, keyed by dev:ino. Used by the
|
|
450
|
+
// deletion-propagation loop below to recognize an "orphan" that is really just the
|
|
451
|
+
// same file this pull wrote under a different manifest key (e.g. a case-only title
|
|
452
|
+
// rename on a case-insensitive filesystem) — that file must never be deleted.
|
|
453
|
+
const writtenIdentities = new Set();
|
|
454
|
+
for (const file of files) {
|
|
455
|
+
try {
|
|
456
|
+
const stat = fs_1.default.statSync(path_1.default.join(destination, ...file.path.split('/')));
|
|
457
|
+
writtenIdentities.add(`${stat.dev}:${stat.ino}`);
|
|
458
|
+
}
|
|
459
|
+
catch {
|
|
460
|
+
continue;
|
|
461
|
+
}
|
|
462
|
+
}
|
|
463
|
+
const manifest = { folder_path: folderPath, docs: manifestDocs };
|
|
464
|
+
(0, docs_manifest_1.writeManifest)(destination, manifest);
|
|
465
|
+
for (const warning of [...extraWarnings, ...warnings]) {
|
|
466
|
+
process.stderr.write(chalk_1.default.yellow(`${warning}\n`));
|
|
467
|
+
}
|
|
468
|
+
const removed = [];
|
|
469
|
+
const keptModified = [];
|
|
470
|
+
// Deletion propagation is only safe when the old manifest describes the SAME
|
|
471
|
+
// folder we just pulled. Otherwise every tracked file looks like an orphan and
|
|
472
|
+
// the unmodified ones would be deleted. The single-doc fallback writes a
|
|
473
|
+
// one-entry manifest, so it can never speak for a folder's contents either.
|
|
474
|
+
const canPropagateDeletions = previousManifest !== null &&
|
|
475
|
+
!usedSingleDocFallback &&
|
|
476
|
+
previousManifest.folder_path === folderPath;
|
|
477
|
+
if (previousManifest !== null && !canPropagateDeletions) {
|
|
478
|
+
if (usedSingleDocFallback) {
|
|
479
|
+
process.stderr.write(chalk_1.default.yellow("deletions not propagated: single-doc pull cannot speak for a folder's contents\n"));
|
|
480
|
+
}
|
|
481
|
+
else if (previousManifest.folder_path !== folderPath) {
|
|
482
|
+
process.stderr.write(chalk_1.default.yellow(`deletions not propagated: this directory tracks "${previousManifest.folder_path}", not "${folderPath}"\n`));
|
|
483
|
+
}
|
|
484
|
+
}
|
|
485
|
+
const keptModifiedMedia = new Set();
|
|
486
|
+
if (canPropagateDeletions) {
|
|
487
|
+
const destPrefix = path_1.default.resolve(destination) + path_1.default.sep;
|
|
488
|
+
const realDest = fs_1.default.realpathSync(destination);
|
|
489
|
+
for (const [relPath, entry] of Object.entries(previousManifest.docs)) {
|
|
490
|
+
if (manifestDocs[relPath])
|
|
491
|
+
continue;
|
|
492
|
+
const absPath = path_1.default.resolve(destination, ...relPath.split('/'));
|
|
493
|
+
// Containment: a hand-edited or corrupt manifest key such as "../../etc/passwd"
|
|
494
|
+
// would otherwise resolve outside the pull destination. `docs pull` never writes
|
|
495
|
+
// such a key (titles are sanitized), but this loop is the only code in the CLI
|
|
496
|
+
// that deletes files — never let it act on a path it did not create.
|
|
497
|
+
if (!absPath.startsWith(destPrefix))
|
|
498
|
+
continue;
|
|
499
|
+
// Only ever remove regular files. A directory here means a corrupt manifest;
|
|
500
|
+
// rmSync would throw mid-pull, leaving a half-deleted tree.
|
|
501
|
+
//
|
|
502
|
+
// The whole entry is guarded: the new manifest is already on disk by now, so an
|
|
503
|
+
// uncaught throw would abort the report, silently skip every later orphan, and
|
|
504
|
+
// print a raw stack trace instead of this command's normal error format. One bad
|
|
505
|
+
// entry must cost only that entry.
|
|
506
|
+
try {
|
|
507
|
+
const stat = fs_1.default.statSync(absPath);
|
|
508
|
+
if (!stat.isFile())
|
|
509
|
+
continue;
|
|
510
|
+
// Physical containment: the lexical check above only guards the string. If
|
|
511
|
+
// an intermediate path segment (e.g. "sub" in "sub/x.png") is a symlink to a
|
|
512
|
+
// directory OUTSIDE the destination, statSync/readFileSync/rmSync all follow
|
|
513
|
+
// it transparently. Resolve the real parent directory and require it to
|
|
514
|
+
// physically live under the real destination before ever touching the file.
|
|
515
|
+
const realParent = fs_1.default.realpathSync(path_1.default.dirname(absPath));
|
|
516
|
+
if (realParent !== realDest && !realParent.startsWith(realDest + path_1.default.sep))
|
|
517
|
+
continue;
|
|
518
|
+
// Identity: never delete a file this pull just wrote. A case-only title
|
|
519
|
+
// rename on a case-insensitive filesystem (or a hand-edited manifest with a
|
|
520
|
+
// hardlinked entry) can make an "orphan" key resolve to the very file the
|
|
521
|
+
// new manifest just wrote under a different key — bytes trivially match.
|
|
522
|
+
const identity = `${stat.dev}:${stat.ino}`;
|
|
523
|
+
if (writtenIdentities.has(identity))
|
|
524
|
+
continue;
|
|
525
|
+
const currentHash = (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(absPath));
|
|
526
|
+
if (entry.body_sha256 != null && entry.body_sha256 === currentHash) {
|
|
527
|
+
fs_1.default.rmSync(absPath);
|
|
528
|
+
removed.push(relPath);
|
|
529
|
+
}
|
|
530
|
+
else {
|
|
531
|
+
keptModified.push(relPath);
|
|
532
|
+
if (entry.media)
|
|
533
|
+
keptModifiedMedia.add(relPath);
|
|
534
|
+
}
|
|
535
|
+
}
|
|
536
|
+
catch {
|
|
537
|
+
// Vanished mid-run, unreadable, or refuses inspection: never delete blind.
|
|
538
|
+
continue;
|
|
539
|
+
}
|
|
540
|
+
}
|
|
541
|
+
}
|
|
542
|
+
if (options.json) {
|
|
543
|
+
console.log(JSON.stringify({ manifest, files, removed, kept_modified: keptModified }));
|
|
544
|
+
process.exit(0);
|
|
545
|
+
}
|
|
546
|
+
console.log(chalk_1.default.green(`pulled ${files.length} doc${files.length === 1 ? '' : 's'} → ${destination}`));
|
|
547
|
+
for (const file of files) {
|
|
548
|
+
console.log(chalk_1.default.gray(` ${file.path}`));
|
|
549
|
+
}
|
|
550
|
+
for (const file of removed) {
|
|
551
|
+
console.log(chalk_1.default.gray(`- removed (deleted remotely): ${file}`));
|
|
552
|
+
}
|
|
553
|
+
for (const file of keptModified) {
|
|
554
|
+
process.stderr.write(chalk_1.default.yellow(`! kept ${file} — deleted remotely but modified locally\n`));
|
|
555
|
+
if (keptModifiedMedia.has(file)) {
|
|
556
|
+
process.stderr.write(chalk_1.default.yellow(' (it is now untracked; use `solidactions docs upload` to re-create it)\n'));
|
|
557
|
+
}
|
|
558
|
+
else {
|
|
559
|
+
process.stderr.write(chalk_1.default.yellow(' (it is now untracked; `docs push` will re-create it)\n'));
|
|
560
|
+
}
|
|
561
|
+
}
|
|
562
|
+
process.exit(0);
|
|
563
|
+
}
|
|
564
|
+
/**
|
|
565
|
+
* Entry point called from index.ts.
|
|
566
|
+
*/
|
|
567
|
+
async function docsPull(folder, dest, options) {
|
|
568
|
+
const config = await (0, api_1.requireConfigWithWorkspace)();
|
|
569
|
+
await docsPullWithConfig(folder, dest, options, config);
|
|
570
|
+
}
|