@solidactions/cli 1.27.0 → 1.29.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 +20 -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 +422 -0
- package/dist/commands/docs-push.js +115 -3
- package/dist/commands/docs-upload.js +111 -0
- package/dist/commands/skill-exec.js +61 -0
- package/dist/commands/skill-publish.js +22 -0
- package/dist/commands/skill-pull.js +12 -0
- package/dist/commands/skill-push.js +160 -7
- package/dist/commands/skill-run.js +164 -0
- package/dist/index.js +106 -1
- package/dist/utils/crew.js +72 -0
- package/dist/utils/skill-snapshot.js +89 -0
- package/package.json +1 -1
|
@@ -0,0 +1,422 @@
|
|
|
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.DOCS_MANIFEST = void 0;
|
|
23
|
+
exports.sanitizeSegment = sanitizeSegment;
|
|
24
|
+
exports.sanitizeTitle = sanitizeTitle;
|
|
25
|
+
exports.sha256Hex = sha256Hex;
|
|
26
|
+
exports.docsPullWithConfig = docsPullWithConfig;
|
|
27
|
+
exports.docsPull = docsPull;
|
|
28
|
+
const fs_1 = __importDefault(require("fs"));
|
|
29
|
+
const path_1 = __importDefault(require("path"));
|
|
30
|
+
const crypto_1 = __importDefault(require("crypto"));
|
|
31
|
+
const axios_1 = __importDefault(require("axios"));
|
|
32
|
+
const chalk_1 = __importDefault(require("chalk"));
|
|
33
|
+
const prompts_1 = __importDefault(require("prompts"));
|
|
34
|
+
const api_1 = require("../utils/api");
|
|
35
|
+
const mcp_1 = require("../utils/mcp");
|
|
36
|
+
/** Extension appended to a media file's sanitized title when the title itself has none. */
|
|
37
|
+
const MIME_EXTENSIONS = {
|
|
38
|
+
'image/png': '.png',
|
|
39
|
+
'image/jpeg': '.jpg',
|
|
40
|
+
'image/gif': '.gif',
|
|
41
|
+
'image/webp': '.webp',
|
|
42
|
+
'application/pdf': '.pdf',
|
|
43
|
+
};
|
|
44
|
+
exports.DOCS_MANIFEST = '.solidactions-docs.json';
|
|
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
|
+
/** sha256 hex digest of the given bytes/string, as written to disk. */
|
|
110
|
+
function sha256Hex(data) {
|
|
111
|
+
return crypto_1.default.createHash('sha256').update(data).digest('hex');
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Read `<destination>/.solidactions-docs.json`. Absent or unparseable → null,
|
|
115
|
+
* meaning the destination isn't manifest-tracked (nothing to protect).
|
|
116
|
+
*/
|
|
117
|
+
function readExistingManifest(destination) {
|
|
118
|
+
const manifestPath = path_1.default.join(destination, exports.DOCS_MANIFEST);
|
|
119
|
+
if (!fs_1.default.existsSync(manifestPath)) {
|
|
120
|
+
return null;
|
|
121
|
+
}
|
|
122
|
+
try {
|
|
123
|
+
return JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf8'));
|
|
124
|
+
}
|
|
125
|
+
catch {
|
|
126
|
+
return null;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Compare each manifest-tracked file against its recorded `body_sha256` to
|
|
131
|
+
* find unpushed local edits. An entry without a hash (old manifest) or whose
|
|
132
|
+
* file is missing locally is never reported as modified — graceful
|
|
133
|
+
* degradation to "no detection" rather than a false refusal.
|
|
134
|
+
*/
|
|
135
|
+
function detectLocalModifications(destination, manifest) {
|
|
136
|
+
const modified = [];
|
|
137
|
+
for (const [relPath, entry] of Object.entries(manifest.docs)) {
|
|
138
|
+
if (entry.body_sha256 == null)
|
|
139
|
+
continue;
|
|
140
|
+
const absPath = path_1.default.join(destination, relPath);
|
|
141
|
+
if (!fs_1.default.existsSync(absPath))
|
|
142
|
+
continue;
|
|
143
|
+
const currentHash = sha256Hex(fs_1.default.readFileSync(absPath));
|
|
144
|
+
if (currentHash !== entry.body_sha256) {
|
|
145
|
+
modified.push(relPath);
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
return modified;
|
|
149
|
+
}
|
|
150
|
+
/** The last non-empty path segment of a '/'-separated folder path. */
|
|
151
|
+
function lastSegment(folderPath) {
|
|
152
|
+
const segments = folderPath.split('/').filter(Boolean);
|
|
153
|
+
return segments[segments.length - 1] ?? folderPath;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* BFS-walk `folderPath` via `docs_vault list`, collecting every doc row with
|
|
157
|
+
* its relative folder path. Returns null (with the list error message
|
|
158
|
+
* already known to the caller) if the root list call fails.
|
|
159
|
+
*/
|
|
160
|
+
async function listTree(config, folderPath) {
|
|
161
|
+
const rows = [];
|
|
162
|
+
const queue = [{ folder_path: folderPath, relative: '' }];
|
|
163
|
+
let first = true;
|
|
164
|
+
while (queue.length > 0) {
|
|
165
|
+
const { folder_path, relative } = queue.shift();
|
|
166
|
+
const result = await (0, mcp_1.callDocsTool)(config, 'docs_vault', { action: 'list', folder_path });
|
|
167
|
+
if (!result.ok) {
|
|
168
|
+
// A subfolder returned by the server itself failed to list is surfaced the
|
|
169
|
+
// same way as a root failure — only the root failure triggers the
|
|
170
|
+
// single-doc fallback (isRoot distinguishes the two).
|
|
171
|
+
return { ok: false, isRoot: first, code: result.data?.code ?? 'unknown_error', message: result.data?.message ?? 'MCP returned an error with no message' };
|
|
172
|
+
}
|
|
173
|
+
first = false;
|
|
174
|
+
for (const folder of result.data?.folders ?? []) {
|
|
175
|
+
const safeName = sanitizeSegment(folder.name);
|
|
176
|
+
const childRelative = relative ? `${relative}/${safeName}` : safeName;
|
|
177
|
+
queue.push({ folder_path: folder.folder_path, relative: childRelative });
|
|
178
|
+
}
|
|
179
|
+
for (const doc of result.data?.docs ?? []) {
|
|
180
|
+
rows.push({ id: doc.id, title: doc.title, relative });
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
return { ok: true, rows };
|
|
184
|
+
}
|
|
185
|
+
/** The bulk_read row status that means "body/revision were returned successfully". */
|
|
186
|
+
const BULK_READ_OK_STATUS = 'found';
|
|
187
|
+
/**
|
|
188
|
+
* Fetch bodies + revisions for every collected row via bulk_read, chunked at
|
|
189
|
+
* CHUNK_SIZE ids. A row whose status isn't `BULK_READ_OK_STATUS` (e.g. a
|
|
190
|
+
* server-side `error` or `not_found`), or a requested id absent from the
|
|
191
|
+
* response entirely, is soft-skipped: a warning naming the doc, no file
|
|
192
|
+
* written, no manifest entry — mirroring the media download soft-skip.
|
|
193
|
+
*/
|
|
194
|
+
async function fetchBodies(config, rows) {
|
|
195
|
+
const byId = new Map();
|
|
196
|
+
for (const row of rows)
|
|
197
|
+
byId.set(row.id, row);
|
|
198
|
+
const fetched = [];
|
|
199
|
+
const warnings = [];
|
|
200
|
+
for (let i = 0; i < rows.length; i += CHUNK_SIZE) {
|
|
201
|
+
const chunk = rows.slice(i, i + CHUNK_SIZE);
|
|
202
|
+
const result = await (0, mcp_1.callDocsTool)(config, 'docs_vault', {
|
|
203
|
+
action: 'bulk_read',
|
|
204
|
+
items: chunk.map((r) => ({ id: r.id })),
|
|
205
|
+
});
|
|
206
|
+
if (!result.ok) {
|
|
207
|
+
const code = result.data?.code ?? 'unknown_error';
|
|
208
|
+
const message = result.data?.message ?? 'MCP returned an error with no message';
|
|
209
|
+
process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
|
|
210
|
+
process.exit(1);
|
|
211
|
+
}
|
|
212
|
+
const resultRows = result.data?.results ?? [];
|
|
213
|
+
const seenIds = new Set();
|
|
214
|
+
for (const row of resultRows) {
|
|
215
|
+
const original = byId.get(row.id);
|
|
216
|
+
if (!original)
|
|
217
|
+
continue;
|
|
218
|
+
seenIds.add(row.id);
|
|
219
|
+
if (row.status !== BULK_READ_OK_STATUS) {
|
|
220
|
+
warnings.push(`warn: skipping doc ${row.id} (${original.title}): bulk_read returned status "${row.status ?? 'unknown'}"`);
|
|
221
|
+
continue;
|
|
222
|
+
}
|
|
223
|
+
fetched.push({
|
|
224
|
+
...original,
|
|
225
|
+
body: row.body ?? '',
|
|
226
|
+
current_revision_id: row.current_revision_id ?? null,
|
|
227
|
+
properties: row.properties ?? {},
|
|
228
|
+
});
|
|
229
|
+
}
|
|
230
|
+
for (const requested of chunk) {
|
|
231
|
+
if (!seenIds.has(requested.id)) {
|
|
232
|
+
warnings.push(`warn: skipping doc ${requested.id} (${requested.title}): missing from bulk_read results`);
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
return { fetched, warnings };
|
|
237
|
+
}
|
|
238
|
+
/**
|
|
239
|
+
* Write every fetched doc to disk under `destination`, tracking sanitized
|
|
240
|
+
* filename collisions per directory (suffix "-2", "-3", ... before the
|
|
241
|
+
* extension). Returns the manifest docs map, the ordered list of written
|
|
242
|
+
* files (for --json output), and any non-fatal warnings (e.g. a media
|
|
243
|
+
* signed-URL download that failed).
|
|
244
|
+
*/
|
|
245
|
+
async function writeDocs(destination, docs, config) {
|
|
246
|
+
const manifestDocs = {};
|
|
247
|
+
const files = [];
|
|
248
|
+
const warnings = [];
|
|
249
|
+
const usedNamesByDir = new Map();
|
|
250
|
+
for (const doc of docs) {
|
|
251
|
+
const dirRel = doc.relative;
|
|
252
|
+
const dirAbs = dirRel ? path_1.default.join(destination, ...dirRel.split('/')) : destination;
|
|
253
|
+
fs_1.default.mkdirSync(dirAbs, { recursive: true });
|
|
254
|
+
let used = usedNamesByDir.get(dirRel);
|
|
255
|
+
if (!used) {
|
|
256
|
+
used = new Set();
|
|
257
|
+
usedNamesByDir.set(dirRel, used);
|
|
258
|
+
}
|
|
259
|
+
const media = isMediaCandidate(doc) ? await resolveMedia(config, doc) : { isMedia: false };
|
|
260
|
+
if (media.warning)
|
|
261
|
+
warnings.push(media.warning);
|
|
262
|
+
const sanitized = sanitizeTitle(doc.title);
|
|
263
|
+
let base = sanitized;
|
|
264
|
+
let ext = '.md';
|
|
265
|
+
if (media.isMedia) {
|
|
266
|
+
const titleExt = path_1.default.extname(sanitized);
|
|
267
|
+
if (titleExt) {
|
|
268
|
+
base = sanitized.slice(0, -titleExt.length);
|
|
269
|
+
ext = titleExt;
|
|
270
|
+
}
|
|
271
|
+
else {
|
|
272
|
+
base = sanitized;
|
|
273
|
+
ext = (media.mime && MIME_EXTENSIONS[media.mime]) ?? '';
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
let candidate = base;
|
|
277
|
+
let suffix = 2;
|
|
278
|
+
while (used.has(`${candidate}${ext}`)) {
|
|
279
|
+
candidate = `${base}-${suffix}`;
|
|
280
|
+
suffix++;
|
|
281
|
+
}
|
|
282
|
+
used.add(`${candidate}${ext}`);
|
|
283
|
+
const fileName = `${candidate}${ext}`;
|
|
284
|
+
const relPath = dirRel ? `${dirRel}/${fileName}` : fileName;
|
|
285
|
+
let bodySha256;
|
|
286
|
+
if (media.isMedia) {
|
|
287
|
+
if (media.bytes) {
|
|
288
|
+
fs_1.default.writeFileSync(path_1.default.join(dirAbs, fileName), media.bytes);
|
|
289
|
+
files.push({ path: relPath, action: 'written' });
|
|
290
|
+
bodySha256 = sha256Hex(media.bytes);
|
|
291
|
+
}
|
|
292
|
+
else {
|
|
293
|
+
// Download failure: warning already recorded above; skip the write but
|
|
294
|
+
// still record the manifest entry below so the doc isn't silently lost.
|
|
295
|
+
bodySha256 = null;
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
else {
|
|
299
|
+
fs_1.default.writeFileSync(path_1.default.join(dirAbs, fileName), doc.body, 'utf8');
|
|
300
|
+
files.push({ path: relPath, action: 'written' });
|
|
301
|
+
bodySha256 = sha256Hex(doc.body);
|
|
302
|
+
}
|
|
303
|
+
manifestDocs[relPath] = {
|
|
304
|
+
id: doc.id,
|
|
305
|
+
title: doc.title,
|
|
306
|
+
current_revision_id: doc.current_revision_id,
|
|
307
|
+
media: media.isMedia,
|
|
308
|
+
body_sha256: bodySha256,
|
|
309
|
+
};
|
|
310
|
+
}
|
|
311
|
+
return { manifestDocs, files, warnings };
|
|
312
|
+
}
|
|
313
|
+
/**
|
|
314
|
+
* Core implementation — accepts an injected config so tests can point at a
|
|
315
|
+
* stub server without touching the filesystem config.
|
|
316
|
+
*/
|
|
317
|
+
async function docsPullWithConfig(folderPath, dest, options, config) {
|
|
318
|
+
const destInput = dest ?? `./${lastSegment(folderPath)}`;
|
|
319
|
+
const destination = path_1.default.resolve(destInput);
|
|
320
|
+
// Overwrite-confirm: warn + confirm on a non-empty destination before any network I/O.
|
|
321
|
+
if (fs_1.default.existsSync(destination)) {
|
|
322
|
+
if (!fs_1.default.statSync(destination).isDirectory()) {
|
|
323
|
+
process.stderr.write(chalk_1.default.red(`error: destination "${destination}" exists and is not a directory.\n`));
|
|
324
|
+
process.exit(1);
|
|
325
|
+
}
|
|
326
|
+
// Unpushed-local-changes protection: before any writes or network I/O, compare
|
|
327
|
+
// manifest-tracked files against their pull-time body_sha256. --overwrite is the
|
|
328
|
+
// only way past a refusal; plain --yes still only covers the generic non-empty
|
|
329
|
+
// confirmation below.
|
|
330
|
+
const existingManifest = readExistingManifest(destination);
|
|
331
|
+
if (existingManifest && !options.overwrite) {
|
|
332
|
+
const modified = detectLocalModifications(destination, existingManifest);
|
|
333
|
+
if (modified.length > 0) {
|
|
334
|
+
const noun = modified.length === 1 ? 'file has' : 'files have';
|
|
335
|
+
process.stderr.write(chalk_1.default.red(`${modified.length} ${noun} unpushed local changes:\n`));
|
|
336
|
+
for (const file of modified) {
|
|
337
|
+
process.stderr.write(chalk_1.default.red(` ${file}\n`));
|
|
338
|
+
}
|
|
339
|
+
process.stderr.write(chalk_1.default.red('push your changes first, or pass --overwrite to discard them.\n'));
|
|
340
|
+
process.exit(1);
|
|
341
|
+
}
|
|
342
|
+
}
|
|
343
|
+
const entries = fs_1.default.readdirSync(destination);
|
|
344
|
+
if (entries.length > 0 && !options.yes && !options.overwrite) {
|
|
345
|
+
console.log(chalk_1.default.yellow(`Destination "${destination}" is not empty (${entries.length} items).`));
|
|
346
|
+
console.log(chalk_1.default.yellow('Pulling will overwrite existing files.'));
|
|
347
|
+
const response = await (0, prompts_1.default)({
|
|
348
|
+
type: 'confirm',
|
|
349
|
+
name: 'proceed',
|
|
350
|
+
message: 'Continue?',
|
|
351
|
+
initial: false,
|
|
352
|
+
});
|
|
353
|
+
if (!response.proceed) {
|
|
354
|
+
console.log(chalk_1.default.gray('Cancelled.'));
|
|
355
|
+
process.exit(0);
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
}
|
|
359
|
+
let rows;
|
|
360
|
+
const listResult = await listTree(config, folderPath);
|
|
361
|
+
if (listResult.ok) {
|
|
362
|
+
rows = listResult.rows;
|
|
363
|
+
}
|
|
364
|
+
else if (listResult.isRoot && listResult.code === 'folder_path_not_found') {
|
|
365
|
+
// Single-doc fallback: the target might be a doc path, not a folder.
|
|
366
|
+
const dir = path_1.default.dirname(folderPath);
|
|
367
|
+
const title = path_1.default.basename(folderPath);
|
|
368
|
+
const readArgs = { action: 'read', path: dir === '.' ? { title } : { folder_path: dir, title } };
|
|
369
|
+
const readResult = await (0, mcp_1.callDocsTool)(config, 'docs_vault', readArgs);
|
|
370
|
+
if (!readResult.ok) {
|
|
371
|
+
const readCode = readResult.data?.code ?? 'unknown_error';
|
|
372
|
+
const readMessage = readResult.data?.message ?? 'MCP returned an error with no message';
|
|
373
|
+
process.stderr.write(chalk_1.default.red(`error: ${listResult.code}: ${listResult.message}\n`));
|
|
374
|
+
process.stderr.write(chalk_1.default.red(`error: ${readCode}: ${readMessage}\n`));
|
|
375
|
+
process.exit(1);
|
|
376
|
+
}
|
|
377
|
+
const data = readResult.data;
|
|
378
|
+
const fetched = [{
|
|
379
|
+
id: data.id,
|
|
380
|
+
title: data.title,
|
|
381
|
+
relative: '',
|
|
382
|
+
body: data.body ?? '',
|
|
383
|
+
current_revision_id: data.current_revision_id ?? null,
|
|
384
|
+
properties: data.properties ?? {},
|
|
385
|
+
}];
|
|
386
|
+
await report(destination, folderPath, fetched, options, config, []);
|
|
387
|
+
return;
|
|
388
|
+
}
|
|
389
|
+
else {
|
|
390
|
+
process.stderr.write(chalk_1.default.red(`error: ${listResult.code}: ${listResult.message}\n`));
|
|
391
|
+
process.exit(1);
|
|
392
|
+
return;
|
|
393
|
+
}
|
|
394
|
+
const { fetched, warnings: fetchWarnings } = await fetchBodies(config, rows);
|
|
395
|
+
await report(destination, folderPath, fetched, options, config, fetchWarnings);
|
|
396
|
+
}
|
|
397
|
+
/** Write the docs + manifest to disk and print the result (chalk lines or --json). */
|
|
398
|
+
async function report(destination, folderPath, fetched, options, config, extraWarnings) {
|
|
399
|
+
fs_1.default.mkdirSync(destination, { recursive: true });
|
|
400
|
+
const { manifestDocs, files, warnings } = await writeDocs(destination, fetched, config);
|
|
401
|
+
const manifest = { folder_path: folderPath, docs: manifestDocs };
|
|
402
|
+
fs_1.default.writeFileSync(path_1.default.join(destination, exports.DOCS_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
|
|
403
|
+
for (const warning of [...extraWarnings, ...warnings]) {
|
|
404
|
+
process.stderr.write(chalk_1.default.yellow(`${warning}\n`));
|
|
405
|
+
}
|
|
406
|
+
if (options.json) {
|
|
407
|
+
console.log(JSON.stringify({ manifest, files }));
|
|
408
|
+
process.exit(0);
|
|
409
|
+
}
|
|
410
|
+
console.log(chalk_1.default.green(`pulled ${files.length} doc${files.length === 1 ? '' : 's'} → ${destination}`));
|
|
411
|
+
for (const file of files) {
|
|
412
|
+
console.log(chalk_1.default.gray(` ${file.path}`));
|
|
413
|
+
}
|
|
414
|
+
process.exit(0);
|
|
415
|
+
}
|
|
416
|
+
/**
|
|
417
|
+
* Entry point called from index.ts.
|
|
418
|
+
*/
|
|
419
|
+
async function docsPull(folder, dest, options) {
|
|
420
|
+
const config = await (0, api_1.requireConfigWithWorkspace)();
|
|
421
|
+
await docsPullWithConfig(folder, dest, options, config);
|
|
422
|
+
}
|
|
@@ -19,7 +19,25 @@ const path_1 = __importDefault(require("path"));
|
|
|
19
19
|
const chalk_1 = __importDefault(require("chalk"));
|
|
20
20
|
const api_1 = require("../utils/api");
|
|
21
21
|
const mcp_1 = require("../utils/mcp");
|
|
22
|
+
const docs_pull_1 = require("./docs-pull");
|
|
22
23
|
const CHUNK_SIZE = 50;
|
|
24
|
+
/**
|
|
25
|
+
* Read `<absDir>/.solidactions-docs.json`. Absent or unparseable → null,
|
|
26
|
+
* meaning nothing under `absDir` is guarded (sidecar convention from D1/D2).
|
|
27
|
+
*/
|
|
28
|
+
function readManifest(absDir) {
|
|
29
|
+
const manifestPath = path_1.default.join(absDir, docs_pull_1.DOCS_MANIFEST);
|
|
30
|
+
if (!fs_1.default.existsSync(manifestPath)) {
|
|
31
|
+
return null;
|
|
32
|
+
}
|
|
33
|
+
try {
|
|
34
|
+
return JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf8'));
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
process.stderr.write(chalk_1.default.yellow(`warn: ${docs_pull_1.DOCS_MANIFEST} exists but could not be parsed — all files will be treated as untracked\n`));
|
|
38
|
+
return null;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
23
41
|
/**
|
|
24
42
|
* Recursively walk `dir` and collect all *.md files.
|
|
25
43
|
* Returns a list of absolute paths.
|
|
@@ -118,7 +136,72 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
118
136
|
process.stderr.write(chalk_1.default.red(`error: no .md files found under "${dir}" — nothing to push.\n`));
|
|
119
137
|
process.exit(1);
|
|
120
138
|
}
|
|
121
|
-
|
|
139
|
+
// Partition into tracked (relative path present in the pull manifest) vs. untracked.
|
|
140
|
+
// A missing/unparseable manifest means nothing is tracked — everything is untracked,
|
|
141
|
+
// matching the existing (pre-drift-guard) bulk_create behavior byte-for-byte.
|
|
142
|
+
const manifest = readManifest(absDir);
|
|
143
|
+
const trackedFiles = [];
|
|
144
|
+
const untrackedFiles = [];
|
|
145
|
+
for (const f of allFiles) {
|
|
146
|
+
const relPath = path_1.default.relative(absDir, f).split(path_1.default.sep).join('/');
|
|
147
|
+
if (manifest?.docs[relPath]) {
|
|
148
|
+
trackedFiles.push({ absPath: f, relPath });
|
|
149
|
+
}
|
|
150
|
+
else {
|
|
151
|
+
untrackedFiles.push(f);
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
const trackedWritten = [];
|
|
155
|
+
const trackedDrifted = [];
|
|
156
|
+
const trackedPlanned = [];
|
|
157
|
+
const trackedUnchanged = [];
|
|
158
|
+
for (const { absPath, relPath } of trackedFiles) {
|
|
159
|
+
const entry = manifest.docs[relPath];
|
|
160
|
+
const body = fs_1.default.readFileSync(absPath, 'utf8');
|
|
161
|
+
const bodyHash = (0, docs_pull_1.sha256Hex)(body);
|
|
162
|
+
// Skip-unchanged applies regardless of --force or --dry-run: force answers
|
|
163
|
+
// drift, not staleness, and an old manifest lacking body_sha256 (undefined)
|
|
164
|
+
// never matches, so it always falls through to a write (graceful degradation).
|
|
165
|
+
if (entry.body_sha256 != null && entry.body_sha256 === bodyHash) {
|
|
166
|
+
trackedUnchanged.push({ file: relPath, id: entry.id });
|
|
167
|
+
continue;
|
|
168
|
+
}
|
|
169
|
+
// --dry-run must never live-write: preview the tracked doc instead of calling docs_edit.
|
|
170
|
+
if (options.dryRun) {
|
|
171
|
+
trackedPlanned.push({ file: relPath, id: entry.id });
|
|
172
|
+
continue;
|
|
173
|
+
}
|
|
174
|
+
const editArgs = { action: 'write', id: entry.id, body };
|
|
175
|
+
if (!options.force && entry.current_revision_id !== null) {
|
|
176
|
+
editArgs.base_revision = entry.current_revision_id;
|
|
177
|
+
}
|
|
178
|
+
let mcpResult;
|
|
179
|
+
try {
|
|
180
|
+
mcpResult = await (0, mcp_1.callDocsTool)(config, 'docs_edit', editArgs);
|
|
181
|
+
}
|
|
182
|
+
catch (e) {
|
|
183
|
+
process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
|
|
184
|
+
process.exit(1);
|
|
185
|
+
}
|
|
186
|
+
if (!mcpResult.ok) {
|
|
187
|
+
const code = mcpResult.data?.code ?? 'unknown_error';
|
|
188
|
+
const message = mcpResult.data?.message ?? 'MCP returned an error with no message';
|
|
189
|
+
process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
|
|
190
|
+
process.exit(1);
|
|
191
|
+
}
|
|
192
|
+
const data = mcpResult.data;
|
|
193
|
+
if (data?.stale === true || data?.code === 'stale_revision') {
|
|
194
|
+
trackedDrifted.push({ file: relPath, their: data.current_revision_id ?? null, base: entry.current_revision_id });
|
|
195
|
+
continue;
|
|
196
|
+
}
|
|
197
|
+
entry.current_revision_id = data?.current_revision_id ?? entry.current_revision_id;
|
|
198
|
+
entry.body_sha256 = bodyHash;
|
|
199
|
+
trackedWritten.push({ file: relPath, id: entry.id, current_revision_id: entry.current_revision_id });
|
|
200
|
+
// Persist immediately so a later failure (another tracked write, or an
|
|
201
|
+
// untracked bulk_create error) never loses this file's refreshed revision.
|
|
202
|
+
fs_1.default.writeFileSync(path_1.default.join(absDir, docs_pull_1.DOCS_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
|
|
203
|
+
}
|
|
204
|
+
const items = untrackedFiles.map((f) => fileToItem(f, absDir));
|
|
122
205
|
// Chunk into groups of CHUNK_SIZE
|
|
123
206
|
const chunks = [];
|
|
124
207
|
for (let i = 0; i < items.length; i += CHUNK_SIZE) {
|
|
@@ -184,16 +267,38 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
184
267
|
missing: r.property_validation.missing ?? [],
|
|
185
268
|
invalid: r.property_validation.invalid ?? [],
|
|
186
269
|
}));
|
|
270
|
+
const exitCode = trackedDrifted.length > 0 ? 1 : 0;
|
|
187
271
|
// --json: output single JSON object
|
|
188
272
|
if (options.json) {
|
|
189
273
|
console.log(JSON.stringify({
|
|
190
274
|
summary: mergedSummary,
|
|
191
275
|
pending: pendingItems,
|
|
192
276
|
results: allResultRows,
|
|
277
|
+
tracked: { written: trackedWritten, drifted: trackedDrifted, planned: trackedPlanned, unchanged: trackedUnchanged },
|
|
193
278
|
}));
|
|
194
|
-
process.exit(
|
|
279
|
+
process.exit(exitCode);
|
|
195
280
|
}
|
|
196
281
|
// Human-readable output
|
|
282
|
+
if (options.dryRun) {
|
|
283
|
+
if (trackedPlanned.length > 0) {
|
|
284
|
+
console.log(chalk_1.default.cyan(`tracked: ${trackedPlanned.length} planned write`));
|
|
285
|
+
for (const p of trackedPlanned) {
|
|
286
|
+
console.log(chalk_1.default.gray(` ${p.file}`));
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
if (trackedUnchanged.length > 0) {
|
|
290
|
+
console.log(chalk_1.default.gray(`tracked: ${trackedUnchanged.length} planned unchanged (skip)`));
|
|
291
|
+
for (const u of trackedUnchanged) {
|
|
292
|
+
console.log(chalk_1.default.gray(` ${u.file}`));
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
else if (trackedWritten.length > 0 || trackedDrifted.length > 0 || trackedUnchanged.length > 0) {
|
|
297
|
+
console.log(chalk_1.default.green(`tracked: ${trackedWritten.length} written, ${trackedDrifted.length} drifted, ${trackedUnchanged.length} unchanged`));
|
|
298
|
+
for (const w of trackedWritten) {
|
|
299
|
+
console.log(chalk_1.default.gray(` ${w.file}`));
|
|
300
|
+
}
|
|
301
|
+
}
|
|
197
302
|
const summaryLine = formatSummaryLine(mergedSummary, !!options.dryRun);
|
|
198
303
|
if (options.dryRun) {
|
|
199
304
|
console.log(chalk_1.default.cyan(`[dry-run preview] ${summaryLine}`));
|
|
@@ -213,7 +318,14 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
213
318
|
}
|
|
214
319
|
}
|
|
215
320
|
}
|
|
216
|
-
|
|
321
|
+
if (trackedDrifted.length > 0) {
|
|
322
|
+
process.stderr.write(chalk_1.default.red(`\ndrift: ${trackedDrifted.length} tracked doc${trackedDrifted.length === 1 ? '' : 's'} changed on the server since the last pull:\n`));
|
|
323
|
+
for (const d of trackedDrifted) {
|
|
324
|
+
process.stderr.write(chalk_1.default.red(` ${d.file} (local base_revision ${d.base}, server now at ${d.their})\n`));
|
|
325
|
+
}
|
|
326
|
+
process.stderr.write(chalk_1.default.red('re-pull to merge, or pass --force to overwrite\n'));
|
|
327
|
+
}
|
|
328
|
+
process.exit(exitCode);
|
|
217
329
|
}
|
|
218
330
|
/**
|
|
219
331
|
* Entry point called from index.ts.
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
36
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
37
|
+
};
|
|
38
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
39
|
+
exports.docsUpload = docsUpload;
|
|
40
|
+
const fs = __importStar(require("fs"));
|
|
41
|
+
const path = __importStar(require("path"));
|
|
42
|
+
const axios_1 = __importDefault(require("axios"));
|
|
43
|
+
const form_data_1 = __importDefault(require("form-data"));
|
|
44
|
+
const chalk_1 = __importDefault(require("chalk"));
|
|
45
|
+
const api_1 = require("../utils/api");
|
|
46
|
+
/**
|
|
47
|
+
* Uploads one or more local files to SA-Docs media (`POST /api/v1/docs/media`),
|
|
48
|
+
* sequentially. `--title` is only valid for a single file — with multiple
|
|
49
|
+
* files, every upload would otherwise silently collide on the same title.
|
|
50
|
+
*/
|
|
51
|
+
async function docsUpload(files, options = {}) {
|
|
52
|
+
if (options.title && files.length > 1) {
|
|
53
|
+
console.error(chalk_1.default.red('--title can only be used when uploading a single file.'));
|
|
54
|
+
process.exit(1);
|
|
55
|
+
}
|
|
56
|
+
const config = await (0, api_1.requireConfigWithWorkspace)();
|
|
57
|
+
let hadError = false;
|
|
58
|
+
for (const file of files) {
|
|
59
|
+
const absPath = path.resolve(file);
|
|
60
|
+
const displayName = path.basename(absPath);
|
|
61
|
+
if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) {
|
|
62
|
+
console.error(chalk_1.default.red(`✗ ${displayName} — file not found`));
|
|
63
|
+
hadError = true;
|
|
64
|
+
continue;
|
|
65
|
+
}
|
|
66
|
+
const form = new form_data_1.default();
|
|
67
|
+
form.append('file', fs.createReadStream(absPath));
|
|
68
|
+
if (options.folder)
|
|
69
|
+
form.append('folder_path', options.folder);
|
|
70
|
+
if (options.title)
|
|
71
|
+
form.append('title', options.title);
|
|
72
|
+
try {
|
|
73
|
+
const response = await axios_1.default.post(`${config.host}/api/v1/docs/media`, form, {
|
|
74
|
+
headers: {
|
|
75
|
+
...form.getHeaders(),
|
|
76
|
+
...(0, api_1.getApiHeaders)(config),
|
|
77
|
+
},
|
|
78
|
+
maxContentLength: Infinity,
|
|
79
|
+
maxBodyLength: Infinity,
|
|
80
|
+
});
|
|
81
|
+
// The 201 body nests the created doc under a `doc` key.
|
|
82
|
+
const doc = response.data?.doc;
|
|
83
|
+
const location = doc?.folder_path || '/';
|
|
84
|
+
console.log(chalk_1.default.green(`✓ ${displayName} → ${location} (doc ${doc?.id})`));
|
|
85
|
+
}
|
|
86
|
+
catch (error) {
|
|
87
|
+
hadError = true;
|
|
88
|
+
if (error.response) {
|
|
89
|
+
const { status, data } = error.response;
|
|
90
|
+
if (status === 413) {
|
|
91
|
+
console.error(chalk_1.default.red(`✗ ${displayName} — ${data?.message || 'File exceeds the maximum upload size (20MB).'}`));
|
|
92
|
+
}
|
|
93
|
+
else if (status === 401) {
|
|
94
|
+
console.error(chalk_1.default.red(`✗ ${displayName} — Authentication failed. Run "solidactions login <api-key>" to re-configure.`));
|
|
95
|
+
}
|
|
96
|
+
else if (status === 422) {
|
|
97
|
+
console.error(chalk_1.default.red(`✗ ${displayName} — ${(0, api_1.formatValidationError)(data)}`));
|
|
98
|
+
}
|
|
99
|
+
else {
|
|
100
|
+
console.error(chalk_1.default.red(`✗ ${displayName} — ${data?.message || `request failed with status ${status}`}`));
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
else {
|
|
104
|
+
console.error(chalk_1.default.red(`✗ ${displayName} — ${error.message}`));
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
if (hadError) {
|
|
109
|
+
process.exit(1);
|
|
110
|
+
}
|
|
111
|
+
}
|