@solidactions/cli 1.29.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 +19 -4
- package/dist/commands/docs-pull.js +222 -74
- package/dist/commands/docs-push.js +158 -31
- package/dist/commands/docs-upload.js +79 -8
- package/dist/index.js +2 -1
- package/dist/utils/docs-manifest.js +48 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -168,12 +168,27 @@ Manage docs in SA-Docs (the app's built-in documentation vault). `push` is drift
|
|
|
168
168
|
| Command | Key Flags | Description |
|
|
169
169
|
|---------|-----------|-------------|
|
|
170
170
|
| `docs pull <folder> [dest]` | `-y`, `--overwrite`, `--json` | Download a Docs folder tree (markdown + media) to `dest` (defaults to `./<last-segment>/`); writes a `.solidactions-docs.json` revision manifest (including a `body_sha256` content hash per file) used by `push`'s drift guard. Falls back to fetching a single doc if `folder` is a doc path, not a folder |
|
|
171
|
-
| `docs push <dir>` | `--on-conflict`, `--type`, `--folder`, `--dry-run`, `--force`, `--json` | Recursively upload a local markdown tree. Manifest-tracked files (from a prior `pull`) are written with a `base_revision` guard and reported separately as written/drifted/unchanged; files whose content hash still matches the last pull are skipped as unchanged (no write, no revision bump). `--force` skips the drift guard (unchanged files are still skipped). `--dry-run` previews without writing |
|
|
172
|
-
| `docs upload <files...>` | `--folder`, `--title
|
|
171
|
+
| `docs push <dir>` | `--on-conflict`, `--type`, `--folder`, `--dry-run`, `--force`, `--json` | Recursively upload a local markdown tree. Manifest-tracked files (from a prior `pull`) are written with a `base_revision` guard and reported separately as written/drifted/unchanged; files whose content hash still matches the last pull are skipped as unchanged (no write, no revision bump). Tracked media files whose bytes changed are replaced the same way, under the same guard; a tracked media file missing locally is left alone — `push` never deletes. An untracked binary in the tree is warned about, never uploaded (use `docs upload`). `--force` skips the drift guard (unchanged files are still skipped). `--dry-run` previews without writing. Untracked files are created under the manifest's `folder_path` when `<dir>` came from a `docs pull` (pass `--folder` to override); an untracked file whose title already exists in the target folder is skipped per `--on-conflict` (default `skip`, reported as `duplicate_title`) |
|
|
172
|
+
| `docs upload <files...>` | `--folder`, `--title`, `--replace <doc-id-or-path>` | Upload one or more media files to SA-Docs (requires a token with the "docs" ability); `--title` only valid for a single file. `--replace` swaps the bytes behind an existing media doc instead of creating a new one — see below |
|
|
173
173
|
|
|
174
|
-
|
|
174
|
+
`docs upload <file> --replace <doc-id-or-path>` swaps the bytes behind an existing media doc, keeping its id, title, and folder, so embeds and references keep resolving — the old image stays in the doc's version history. Single file only; cannot be combined with `--title` or `--folder`. A purely numeric argument is a doc id; anything else is a docs path (`marketing/hero.png`), resolved against the doc's **title** — which `docs pull` may have sanitized, so for path-based work on a pulled folder prefer `docs push` instead:
|
|
175
175
|
|
|
176
|
-
|
|
176
|
+
```bash
|
|
177
|
+
solidactions docs upload logo-v2.png --replace 482
|
|
178
|
+
solidactions docs upload logo-v2.png --replace marketing/logo.png
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
**`docs pull` propagates deletions, within limits.** A file is removed locally only when its doc was deleted on the server *and* the file's bytes still match what the last pull gave it (the manifest's `body_sha256`) — anything you've edited locally is kept, with a warning that it's now untracked (re-create a markdown doc with `docs push`, a media doc with `docs upload`). Deletions only propagate when the destination's existing manifest `folder_path` matches the folder you're pulling (so pulling a different folder into a directory holding an old manifest deletes nothing), and never on the single-doc pull path; when propagation is skipped for either reason, `pull` says so. Nothing outside the destination directory is removed: every candidate path is resolved physically (so a symlinked subdirectory cannot lead the delete outside), and a file the same pull just wrote is never deleted, even if a case-only rename makes it look orphaned on a case-insensitive filesystem.
|
|
182
|
+
|
|
183
|
+
**`docs pull --overwrite` is destructive.** If a manifest-tracked file still exists on the server *and* your local copy no longer matches the `body_sha256` recorded at the last pull (i.e. you've edited it and haven't pushed yet), a plain `docs pull` — even with `-y`/`--yes` — refuses with exit 1, naming every modified file, rather than silently discarding your edits. Nothing is written before that refusal. `-y`/`--yes` only bypasses the generic "destination is not empty" prompt; it does not cover locally-modified tracked files. Pass `--overwrite` to discard those local changes and re-pull server content anyway (it also implies `--yes`).
|
|
184
|
+
|
|
185
|
+
You do **not** need `--overwrite` to keep an edited file whose doc was deleted on the server — that case is handled by deletion propagation above, on the default path, and the file is kept with a warning.
|
|
186
|
+
|
|
187
|
+
**Getting a doc id.** `docs upload --replace` accepts a docs path (`marketing/hero.png`), so you rarely need an id. If you want one, `docs pull` records it per file in the destination's `.solidactions-docs.json` sidecar, and `import_outputs` returns the ids it created. Note that `--replace` does not update a pulled directory's manifest. If you replace a tracked image out-of-band and leave the local file untouched, the next `docs push` reports it as **unchanged** and does nothing — the content hash matches, so `push` never asks the server. (Edit the local file too, and the drift guard fires as expected.) Re-pull to resync the manifest.
|
|
188
|
+
|
|
189
|
+
**`docs push` and deleted docs.** If a tracked file's doc was deleted on the server, `push` names it per file (`doc <id> no longer exists (deleted remotely) — re-pull to untrack it, then push to re-create`) and carries on with the other files. Note the deleted doc still holds its title until it leaves the trash, so re-creating it needs the trashed copy restored or purged first — `push` says so if you hit it. `push` exits 1 on drift (a tracked doc moved on since your pull) and on any per-file server error; a deleted doc alone is not an error.
|
|
190
|
+
|
|
191
|
+
**`docs pull` refuses to replace another folder's manifest.** If the destination already tracks a different folder, pulling into it would leave the previously tracked files untracked — and untracked files are not protected from being overwritten by a later pull. `pull` refuses (exit 1, before any network request) and names both folders. Pull into a different directory, or pass `--overwrite` to replace the manifest anyway. This also covers the single-doc pull path, whose one-entry manifest would otherwise clobber a folder's.
|
|
177
192
|
|
|
178
193
|
### workspace
|
|
179
194
|
|
|
@@ -19,20 +19,21 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
|
19
19
|
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
20
20
|
};
|
|
21
21
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
22
|
-
exports.DOCS_MANIFEST = void 0;
|
|
22
|
+
exports.sha256Hex = exports.DOCS_MANIFEST = void 0;
|
|
23
23
|
exports.sanitizeSegment = sanitizeSegment;
|
|
24
24
|
exports.sanitizeTitle = sanitizeTitle;
|
|
25
|
-
exports.sha256Hex = sha256Hex;
|
|
26
25
|
exports.docsPullWithConfig = docsPullWithConfig;
|
|
27
26
|
exports.docsPull = docsPull;
|
|
28
27
|
const fs_1 = __importDefault(require("fs"));
|
|
29
28
|
const path_1 = __importDefault(require("path"));
|
|
30
|
-
const crypto_1 = __importDefault(require("crypto"));
|
|
31
29
|
const axios_1 = __importDefault(require("axios"));
|
|
32
30
|
const chalk_1 = __importDefault(require("chalk"));
|
|
33
31
|
const prompts_1 = __importDefault(require("prompts"));
|
|
34
32
|
const api_1 = require("../utils/api");
|
|
35
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; } });
|
|
36
37
|
/** Extension appended to a media file's sanitized title when the title itself has none. */
|
|
37
38
|
const MIME_EXTENSIONS = {
|
|
38
39
|
'image/png': '.png',
|
|
@@ -41,7 +42,6 @@ const MIME_EXTENSIONS = {
|
|
|
41
42
|
'image/webp': '.webp',
|
|
42
43
|
'application/pdf': '.pdf',
|
|
43
44
|
};
|
|
44
|
-
exports.DOCS_MANIFEST = '.solidactions-docs.json';
|
|
45
45
|
const CHUNK_SIZE = 50;
|
|
46
46
|
/** Characters that are unsafe as filesystem path segments, plus control chars. */
|
|
47
47
|
// eslint-disable-next-line no-control-regex
|
|
@@ -106,26 +106,6 @@ async function resolveMedia(config, doc) {
|
|
|
106
106
|
}
|
|
107
107
|
return { isMedia: true, mime, bytes: Buffer.from(download.data) };
|
|
108
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
109
|
/**
|
|
130
110
|
* Compare each manifest-tracked file against its recorded `body_sha256` to
|
|
131
111
|
* find unpushed local edits. An entry without a hash (old manifest) or whose
|
|
@@ -138,9 +118,18 @@ function detectLocalModifications(destination, manifest) {
|
|
|
138
118
|
if (entry.body_sha256 == null)
|
|
139
119
|
continue;
|
|
140
120
|
const absPath = path_1.default.join(destination, relPath);
|
|
141
|
-
|
|
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())
|
|
142
131
|
continue;
|
|
143
|
-
const currentHash = sha256Hex(fs_1.default.readFileSync(absPath));
|
|
132
|
+
const currentHash = (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(absPath));
|
|
144
133
|
if (currentHash !== entry.body_sha256) {
|
|
145
134
|
modified.push(relPath);
|
|
146
135
|
}
|
|
@@ -236,21 +225,17 @@ async function fetchBodies(config, rows) {
|
|
|
236
225
|
return { fetched, warnings };
|
|
237
226
|
}
|
|
238
227
|
/**
|
|
239
|
-
*
|
|
240
|
-
*
|
|
241
|
-
*
|
|
242
|
-
*
|
|
243
|
-
* signed-URL download that failed).
|
|
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.
|
|
244
232
|
*/
|
|
245
|
-
async function
|
|
246
|
-
const
|
|
247
|
-
const files = [];
|
|
233
|
+
async function planDocs(docs, config) {
|
|
234
|
+
const planned = [];
|
|
248
235
|
const warnings = [];
|
|
249
236
|
const usedNamesByDir = new Map();
|
|
250
237
|
for (const doc of docs) {
|
|
251
238
|
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
239
|
let used = usedNamesByDir.get(dirRel);
|
|
255
240
|
if (!used) {
|
|
256
241
|
used = new Set();
|
|
@@ -283,32 +268,68 @@ async function writeDocs(destination, docs, config) {
|
|
|
283
268
|
const fileName = `${candidate}${ext}`;
|
|
284
269
|
const relPath = dirRel ? `${dirRel}/${fileName}` : fileName;
|
|
285
270
|
let bodySha256;
|
|
271
|
+
let mediaBytes = null;
|
|
286
272
|
if (media.isMedia) {
|
|
287
273
|
if (media.bytes) {
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
bodySha256 = sha256Hex(media.bytes);
|
|
274
|
+
mediaBytes = media.bytes;
|
|
275
|
+
bodySha256 = (0, docs_manifest_1.sha256Hex)(media.bytes);
|
|
291
276
|
}
|
|
292
277
|
else {
|
|
293
|
-
// Download failure: warning already recorded above;
|
|
294
|
-
//
|
|
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.
|
|
295
281
|
bodySha256 = null;
|
|
296
282
|
}
|
|
297
283
|
}
|
|
298
284
|
else {
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
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' });
|
|
302
323
|
}
|
|
303
|
-
manifestDocs[relPath] = {
|
|
304
|
-
id: doc.id,
|
|
305
|
-
title: doc.title,
|
|
306
|
-
current_revision_id: doc.current_revision_id,
|
|
307
|
-
media:
|
|
308
|
-
body_sha256: bodySha256,
|
|
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,
|
|
309
330
|
};
|
|
310
331
|
}
|
|
311
|
-
return { manifestDocs, files
|
|
332
|
+
return { manifestDocs, files };
|
|
312
333
|
}
|
|
313
334
|
/**
|
|
314
335
|
* Core implementation — accepts an injected config so tests can point at a
|
|
@@ -317,29 +338,20 @@ async function writeDocs(destination, docs, config) {
|
|
|
317
338
|
async function docsPullWithConfig(folderPath, dest, options, config) {
|
|
318
339
|
const destInput = dest ?? `./${lastSegment(folderPath)}`;
|
|
319
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;
|
|
320
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).
|
|
321
350
|
if (fs_1.default.existsSync(destination)) {
|
|
322
351
|
if (!fs_1.default.statSync(destination).isDirectory()) {
|
|
323
352
|
process.stderr.write(chalk_1.default.red(`error: destination "${destination}" exists and is not a directory.\n`));
|
|
324
353
|
process.exit(1);
|
|
325
354
|
}
|
|
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
355
|
const entries = fs_1.default.readdirSync(destination);
|
|
344
356
|
if (entries.length > 0 && !options.yes && !options.overwrite) {
|
|
345
357
|
console.log(chalk_1.default.yellow(`Destination "${destination}" is not empty (${entries.length} items).`));
|
|
@@ -356,6 +368,19 @@ async function docsPullWithConfig(folderPath, dest, options, config) {
|
|
|
356
368
|
}
|
|
357
369
|
}
|
|
358
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
|
+
}
|
|
359
384
|
let rows;
|
|
360
385
|
const listResult = await listTree(config, folderPath);
|
|
361
386
|
if (listResult.ok) {
|
|
@@ -363,6 +388,7 @@ async function docsPullWithConfig(folderPath, dest, options, config) {
|
|
|
363
388
|
}
|
|
364
389
|
else if (listResult.isRoot && listResult.code === 'folder_path_not_found') {
|
|
365
390
|
// Single-doc fallback: the target might be a doc path, not a folder.
|
|
391
|
+
usedSingleDocFallback = true;
|
|
366
392
|
const dir = path_1.default.dirname(folderPath);
|
|
367
393
|
const title = path_1.default.basename(folderPath);
|
|
368
394
|
const readArgs = { action: 'read', path: dir === '.' ? { title } : { folder_path: dir, title } };
|
|
@@ -383,7 +409,7 @@ async function docsPullWithConfig(folderPath, dest, options, config) {
|
|
|
383
409
|
current_revision_id: data.current_revision_id ?? null,
|
|
384
410
|
properties: data.properties ?? {},
|
|
385
411
|
}];
|
|
386
|
-
await report(destination, folderPath, fetched, options, config, []);
|
|
412
|
+
await report(destination, folderPath, fetched, options, config, [], previousManifest, usedSingleDocFallback);
|
|
387
413
|
return;
|
|
388
414
|
}
|
|
389
415
|
else {
|
|
@@ -392,25 +418,147 @@ async function docsPullWithConfig(folderPath, dest, options, config) {
|
|
|
392
418
|
return;
|
|
393
419
|
}
|
|
394
420
|
const { fetched, warnings: fetchWarnings } = await fetchBodies(config, rows);
|
|
395
|
-
await report(destination, folderPath, fetched, options, config, fetchWarnings);
|
|
421
|
+
await report(destination, folderPath, fetched, options, config, fetchWarnings, previousManifest, usedSingleDocFallback);
|
|
396
422
|
}
|
|
397
423
|
/** Write the docs + manifest to disk and print the result (chalk lines or --json). */
|
|
398
|
-
async function report(destination, folderPath, fetched, options, config, extraWarnings) {
|
|
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
|
+
}
|
|
399
447
|
fs_1.default.mkdirSync(destination, { recursive: true });
|
|
400
|
-
const { manifestDocs, files
|
|
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
|
+
}
|
|
401
463
|
const manifest = { folder_path: folderPath, docs: manifestDocs };
|
|
402
|
-
|
|
464
|
+
(0, docs_manifest_1.writeManifest)(destination, manifest);
|
|
403
465
|
for (const warning of [...extraWarnings, ...warnings]) {
|
|
404
466
|
process.stderr.write(chalk_1.default.yellow(`${warning}\n`));
|
|
405
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
|
+
}
|
|
406
542
|
if (options.json) {
|
|
407
|
-
console.log(JSON.stringify({ manifest, files }));
|
|
543
|
+
console.log(JSON.stringify({ manifest, files, removed, kept_modified: keptModified }));
|
|
408
544
|
process.exit(0);
|
|
409
545
|
}
|
|
410
546
|
console.log(chalk_1.default.green(`pulled ${files.length} doc${files.length === 1 ? '' : 's'} → ${destination}`));
|
|
411
547
|
for (const file of files) {
|
|
412
548
|
console.log(chalk_1.default.gray(` ${file.path}`));
|
|
413
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
|
+
}
|
|
414
562
|
process.exit(0);
|
|
415
563
|
}
|
|
416
564
|
/**
|
|
@@ -16,28 +16,13 @@ exports.docsPushWithConfig = docsPushWithConfig;
|
|
|
16
16
|
exports.docsPush = docsPush;
|
|
17
17
|
const fs_1 = __importDefault(require("fs"));
|
|
18
18
|
const path_1 = __importDefault(require("path"));
|
|
19
|
+
const axios_1 = __importDefault(require("axios"));
|
|
20
|
+
const form_data_1 = __importDefault(require("form-data"));
|
|
19
21
|
const chalk_1 = __importDefault(require("chalk"));
|
|
20
22
|
const api_1 = require("../utils/api");
|
|
21
23
|
const mcp_1 = require("../utils/mcp");
|
|
22
|
-
const
|
|
24
|
+
const docs_manifest_1 = require("../utils/docs-manifest");
|
|
23
25
|
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
|
-
}
|
|
41
26
|
/**
|
|
42
27
|
* Recursively walk `dir` and collect all *.md files.
|
|
43
28
|
* Returns a list of absolute paths.
|
|
@@ -58,6 +43,35 @@ function walkMarkdownFiles(dir) {
|
|
|
58
43
|
walk(dir);
|
|
59
44
|
return results;
|
|
60
45
|
}
|
|
46
|
+
const SKIP_DIRS = new Set(['node_modules']);
|
|
47
|
+
/**
|
|
48
|
+
* Recursively walk `dir` and collect relative paths of non-.md files that
|
|
49
|
+
* are not present in the manifest — never uploaded by `docs push`; `docs
|
|
50
|
+
* upload` is the way to create media docs from these. Dotfiles and
|
|
51
|
+
* dot-directories are excluded (`entry.name.startsWith('.')` also covers the
|
|
52
|
+
* `.solidactions-docs.json` sidecar itself).
|
|
53
|
+
*/
|
|
54
|
+
function walkUntrackedBinaries(dir, manifest) {
|
|
55
|
+
const results = [];
|
|
56
|
+
const walk = (current) => {
|
|
57
|
+
for (const entry of fs_1.default.readdirSync(current, { withFileTypes: true })) {
|
|
58
|
+
if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name))
|
|
59
|
+
continue;
|
|
60
|
+
const abs = path_1.default.join(current, entry.name);
|
|
61
|
+
if (entry.isDirectory()) {
|
|
62
|
+
walk(abs);
|
|
63
|
+
}
|
|
64
|
+
else if (entry.isFile() && !entry.name.endsWith('.md')) {
|
|
65
|
+
const relPath = path_1.default.relative(dir, abs).split(path_1.default.sep).join('/');
|
|
66
|
+
if (!manifest?.docs[relPath]) {
|
|
67
|
+
results.push(relPath);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
};
|
|
72
|
+
walk(dir);
|
|
73
|
+
return results;
|
|
74
|
+
}
|
|
61
75
|
/**
|
|
62
76
|
* Convert an absolute file path to a bulk_create item, relative to `rootDir`.
|
|
63
77
|
*/
|
|
@@ -132,19 +146,29 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
132
146
|
process.exit(1);
|
|
133
147
|
}
|
|
134
148
|
const allFiles = walkMarkdownFiles(absDir);
|
|
135
|
-
|
|
136
|
-
|
|
149
|
+
// A missing/unparseable manifest means nothing is tracked — everything is untracked,
|
|
150
|
+
// matching the existing (pre-drift-guard) bulk_create behavior byte-for-byte.
|
|
151
|
+
const manifest = (0, docs_manifest_1.readManifest)(absDir, { warnOnParseError: true });
|
|
152
|
+
const trackedMediaEntries = Object.entries(manifest?.docs ?? {}).filter(([, e]) => e.media);
|
|
153
|
+
// A pulled folder of images alone (no .md files) must still be pushable — the early
|
|
154
|
+
// exit only fires when there's truly nothing to push.
|
|
155
|
+
if (allFiles.length === 0 && trackedMediaEntries.length === 0) {
|
|
156
|
+
process.stderr.write(chalk_1.default.red(`error: no .md files or tracked media found under "${dir}" — nothing to push.\n`));
|
|
137
157
|
process.exit(1);
|
|
138
158
|
}
|
|
139
159
|
// Partition into tracked (relative path present in the pull manifest) vs. untracked.
|
|
140
|
-
// A
|
|
141
|
-
//
|
|
142
|
-
|
|
160
|
+
// A media doc titled *.md (e.g. `notes.md`) is bytes, not markdown — it's owned by
|
|
161
|
+
// the media pass below, not this markdown pass, or its bytes would be sent through
|
|
162
|
+
// docs_edit as a text body and corrupt the doc.
|
|
143
163
|
const trackedFiles = [];
|
|
144
164
|
const untrackedFiles = [];
|
|
145
165
|
for (const f of allFiles) {
|
|
146
166
|
const relPath = path_1.default.relative(absDir, f).split(path_1.default.sep).join('/');
|
|
147
|
-
|
|
167
|
+
const entry = manifest?.docs[relPath];
|
|
168
|
+
if (entry?.media) {
|
|
169
|
+
continue;
|
|
170
|
+
}
|
|
171
|
+
if (entry) {
|
|
148
172
|
trackedFiles.push({ absPath: f, relPath });
|
|
149
173
|
}
|
|
150
174
|
else {
|
|
@@ -155,10 +179,11 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
155
179
|
const trackedDrifted = [];
|
|
156
180
|
const trackedPlanned = [];
|
|
157
181
|
const trackedUnchanged = [];
|
|
182
|
+
const trackedMissing = [];
|
|
158
183
|
for (const { absPath, relPath } of trackedFiles) {
|
|
159
184
|
const entry = manifest.docs[relPath];
|
|
160
185
|
const body = fs_1.default.readFileSync(absPath, 'utf8');
|
|
161
|
-
const bodyHash = (0,
|
|
186
|
+
const bodyHash = (0, docs_manifest_1.sha256Hex)(body);
|
|
162
187
|
// Skip-unchanged applies regardless of --force or --dry-run: force answers
|
|
163
188
|
// drift, not staleness, and an old manifest lacking body_sha256 (undefined)
|
|
164
189
|
// never matches, so it always falls through to a write (graceful degradation).
|
|
@@ -185,6 +210,12 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
185
210
|
}
|
|
186
211
|
if (!mcpResult.ok) {
|
|
187
212
|
const code = mcpResult.data?.code ?? 'unknown_error';
|
|
213
|
+
if (code === 'doc_not_found') {
|
|
214
|
+
// The tracked doc was deleted remotely since the last pull. Not a genuine
|
|
215
|
+
// drift/error: report it and move on rather than aborting the whole push.
|
|
216
|
+
trackedMissing.push({ file: relPath, id: entry.id });
|
|
217
|
+
continue;
|
|
218
|
+
}
|
|
188
219
|
const message = mcpResult.data?.message ?? 'MCP returned an error with no message';
|
|
189
220
|
process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
|
|
190
221
|
process.exit(1);
|
|
@@ -199,14 +230,87 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
199
230
|
trackedWritten.push({ file: relPath, id: entry.id, current_revision_id: entry.current_revision_id });
|
|
200
231
|
// Persist immediately so a later failure (another tracked write, or an
|
|
201
232
|
// untracked bulk_create error) never loses this file's refreshed revision.
|
|
202
|
-
|
|
233
|
+
(0, docs_manifest_1.writeManifest)(absDir, manifest);
|
|
203
234
|
}
|
|
235
|
+
// Media pass: tracked binaries (media: true) replace via POST /api/v1/docs/{id}/media,
|
|
236
|
+
// sharing the report arrays above.
|
|
237
|
+
for (const [relPath, entry] of trackedMediaEntries) {
|
|
238
|
+
const absPath = path_1.default.join(absDir, ...relPath.split('/'));
|
|
239
|
+
// Existence before hash: a pull whose media download failed records
|
|
240
|
+
// `media: true, body_sha256: null` and writes no file. push never deletes.
|
|
241
|
+
if (!fs_1.default.existsSync(absPath)) {
|
|
242
|
+
continue;
|
|
243
|
+
}
|
|
244
|
+
// A directory sitting where a media file is tracked (e.g. `hero.png/`) would
|
|
245
|
+
// otherwise make readFileSync throw EISDIR uncaught mid-push. push never deletes,
|
|
246
|
+
// so skip it rather than crash.
|
|
247
|
+
if (!fs_1.default.statSync(absPath).isFile()) {
|
|
248
|
+
continue;
|
|
249
|
+
}
|
|
250
|
+
const bytes = fs_1.default.readFileSync(absPath);
|
|
251
|
+
const bodyHash = (0, docs_manifest_1.sha256Hex)(bytes);
|
|
252
|
+
if (entry.body_sha256 != null && entry.body_sha256 === bodyHash) {
|
|
253
|
+
trackedUnchanged.push({ file: relPath, id: entry.id });
|
|
254
|
+
continue;
|
|
255
|
+
}
|
|
256
|
+
if (options.dryRun) {
|
|
257
|
+
trackedPlanned.push({ file: relPath, id: entry.id });
|
|
258
|
+
continue;
|
|
259
|
+
}
|
|
260
|
+
const form = new form_data_1.default();
|
|
261
|
+
form.append('file', bytes, { filename: path_1.default.basename(relPath) });
|
|
262
|
+
if (!options.force && entry.current_revision_id !== null) {
|
|
263
|
+
form.append('base_revision', String(entry.current_revision_id));
|
|
264
|
+
}
|
|
265
|
+
let doc;
|
|
266
|
+
try {
|
|
267
|
+
const response = await axios_1.default.post(`${config.host}/api/v1/docs/${entry.id}/media`, form, {
|
|
268
|
+
headers: { ...form.getHeaders(), ...(0, api_1.getApiHeaders)(config) },
|
|
269
|
+
maxContentLength: Infinity,
|
|
270
|
+
maxBodyLength: Infinity,
|
|
271
|
+
});
|
|
272
|
+
doc = response.data?.doc;
|
|
273
|
+
}
|
|
274
|
+
catch (error) {
|
|
275
|
+
const status = error.response?.status;
|
|
276
|
+
const data = error.response?.data;
|
|
277
|
+
if (status === 409 && data?.code === 'stale_revision') {
|
|
278
|
+
trackedDrifted.push({ file: relPath, their: data.current_revision_id ?? null, base: entry.current_revision_id });
|
|
279
|
+
continue;
|
|
280
|
+
}
|
|
281
|
+
if (status === 404 && data?.code === 'doc_not_found') {
|
|
282
|
+
// The tracked doc was deleted remotely since the last pull — same
|
|
283
|
+
// treatment as the markdown pass. `media_not_found` is a different case
|
|
284
|
+
// (doc exists but isn't a media doc) and is not handled here.
|
|
285
|
+
trackedMissing.push({ file: relPath, id: entry.id });
|
|
286
|
+
continue;
|
|
287
|
+
}
|
|
288
|
+
process.stderr.write(chalk_1.default.red(`error: ${relPath}: ${data?.message ?? error.message}\n`));
|
|
289
|
+
process.exit(1);
|
|
290
|
+
}
|
|
291
|
+
// The REST presenter names the revision `current_version_id`; MCP docs_edit
|
|
292
|
+
// names it `current_revision_id`. Reading the wrong one nulls the entry and
|
|
293
|
+
// silently disarms the drift guard on every later push.
|
|
294
|
+
entry.current_revision_id = doc?.current_version_id ?? entry.current_revision_id;
|
|
295
|
+
entry.body_sha256 = bodyHash;
|
|
296
|
+
trackedWritten.push({ file: relPath, id: entry.id, current_revision_id: entry.current_revision_id });
|
|
297
|
+
(0, docs_manifest_1.writeManifest)(absDir, manifest);
|
|
298
|
+
}
|
|
299
|
+
const untrackedMedia = walkUntrackedBinaries(absDir, manifest);
|
|
204
300
|
const items = untrackedFiles.map((f) => fileToItem(f, absDir));
|
|
301
|
+
// Untracked docs (new files, or files re-orphaned by a deleted-remotely re-pull)
|
|
302
|
+
// must land back under the folder this directory was pulled into, not the docs
|
|
303
|
+
// root — an explicit --folder always overrides the manifest's recorded folder.
|
|
304
|
+
const effectiveFolder = options.folder ?? manifest?.folder_path;
|
|
305
|
+
const folderInferredFromManifest = !options.folder && !!manifest?.folder_path;
|
|
205
306
|
// Chunk into groups of CHUNK_SIZE
|
|
206
307
|
const chunks = [];
|
|
207
308
|
for (let i = 0; i < items.length; i += CHUNK_SIZE) {
|
|
208
309
|
chunks.push(items.slice(i, i + CHUNK_SIZE));
|
|
209
310
|
}
|
|
311
|
+
if (folderInferredFromManifest && items.length > 0 && !options.json) {
|
|
312
|
+
console.log(chalk_1.default.gray(`creating untracked docs under "${effectiveFolder}" (from ${docs_manifest_1.DOCS_MANIFEST})`));
|
|
313
|
+
}
|
|
210
314
|
const onConflict = options.onConflict ?? 'skip';
|
|
211
315
|
const allResultRows = [];
|
|
212
316
|
let mergedSummary = {};
|
|
@@ -225,9 +329,11 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
225
329
|
if (options.type) {
|
|
226
330
|
callArgs.type = options.type;
|
|
227
331
|
}
|
|
228
|
-
if (
|
|
332
|
+
if (effectiveFolder) {
|
|
229
333
|
// Top-level base for every item; each item's relative_folder_path nests under it.
|
|
230
|
-
|
|
334
|
+
// Explicit --folder wins; otherwise defaults to the manifest's folder_path so
|
|
335
|
+
// untracked docs in a pulled directory land back in the folder they came from.
|
|
336
|
+
callArgs.folder_path = effectiveFolder;
|
|
231
337
|
}
|
|
232
338
|
if (options.dryRun) {
|
|
233
339
|
callArgs.dry_run = true;
|
|
@@ -267,14 +373,17 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
267
373
|
missing: r.property_validation.missing ?? [],
|
|
268
374
|
invalid: r.property_validation.invalid ?? [],
|
|
269
375
|
}));
|
|
270
|
-
|
|
376
|
+
// `done: N errors` on its own says nothing. Name the file and the server's reason.
|
|
377
|
+
const erroredRows = allResultRows.filter((r) => r.status === 'error');
|
|
378
|
+
const exitCode = trackedDrifted.length > 0 || erroredRows.length > 0 ? 1 : 0;
|
|
271
379
|
// --json: output single JSON object
|
|
272
380
|
if (options.json) {
|
|
273
381
|
console.log(JSON.stringify({
|
|
274
382
|
summary: mergedSummary,
|
|
275
383
|
pending: pendingItems,
|
|
276
384
|
results: allResultRows,
|
|
277
|
-
tracked: { written: trackedWritten, drifted: trackedDrifted, planned: trackedPlanned, unchanged: trackedUnchanged },
|
|
385
|
+
tracked: { written: trackedWritten, drifted: trackedDrifted, planned: trackedPlanned, unchanged: trackedUnchanged, missing: trackedMissing },
|
|
386
|
+
untracked_media: untrackedMedia,
|
|
278
387
|
}));
|
|
279
388
|
process.exit(exitCode);
|
|
280
389
|
}
|
|
@@ -299,13 +408,31 @@ async function docsPushWithConfig(dir, options, config) {
|
|
|
299
408
|
console.log(chalk_1.default.gray(` ${w.file}`));
|
|
300
409
|
}
|
|
301
410
|
}
|
|
411
|
+
if (untrackedMedia.length > 0) {
|
|
412
|
+
for (const file of untrackedMedia.slice(0, 10)) {
|
|
413
|
+
process.stderr.write(chalk_1.default.yellow(`${file}: not pushed — use \`solidactions docs upload\`\n`));
|
|
414
|
+
}
|
|
415
|
+
if (untrackedMedia.length > 10) {
|
|
416
|
+
process.stderr.write(chalk_1.default.yellow(`… and ${untrackedMedia.length - 10} more\n`));
|
|
417
|
+
}
|
|
418
|
+
}
|
|
419
|
+
for (const m of trackedMissing) {
|
|
420
|
+
process.stderr.write(chalk_1.default.yellow(`${m.file}: doc ${m.id} no longer exists (deleted remotely) — re-pull to untrack it, then push to re-create (restore or empty it from the trash first, or the title stays taken)\n`));
|
|
421
|
+
}
|
|
302
422
|
const summaryLine = formatSummaryLine(mergedSummary, !!options.dryRun);
|
|
303
423
|
if (options.dryRun) {
|
|
304
424
|
console.log(chalk_1.default.cyan(`[dry-run preview] ${summaryLine}`));
|
|
305
425
|
}
|
|
306
|
-
else {
|
|
426
|
+
else if (items.length > 0) {
|
|
427
|
+
// Suppress "done: 0 docs" when there was nothing to bulk_create — printing it
|
|
428
|
+
// alongside a successful tracked/media write reads as a contradiction.
|
|
307
429
|
console.log(chalk_1.default.green(`done: ${summaryLine}`));
|
|
308
430
|
}
|
|
431
|
+
if (erroredRows.length > 0 && !options.json) {
|
|
432
|
+
for (const row of erroredRows) {
|
|
433
|
+
process.stderr.write(chalk_1.default.red(`${row.file}: ${row.error ?? row.code ?? 'unknown error'}\n`));
|
|
434
|
+
}
|
|
435
|
+
}
|
|
309
436
|
if (pendingItems.length > 0) {
|
|
310
437
|
console.log(chalk_1.default.yellow(`\nProperties pending (${pendingItems.length} doc${pendingItems.length === 1 ? '' : 's'}):`));
|
|
311
438
|
for (const item of pendingItems) {
|
|
@@ -43,6 +43,53 @@ const axios_1 = __importDefault(require("axios"));
|
|
|
43
43
|
const form_data_1 = __importDefault(require("form-data"));
|
|
44
44
|
const chalk_1 = __importDefault(require("chalk"));
|
|
45
45
|
const api_1 = require("../utils/api");
|
|
46
|
+
/**
|
|
47
|
+
* Resolve `--replace` to a doc id. A purely numeric value is an id; anything else
|
|
48
|
+
* is a docs path, resolved against the doc's *title* via GET /docs/by-path.
|
|
49
|
+
*
|
|
50
|
+
* Note the title is not always the local filename: `docs pull` sanitizes
|
|
51
|
+
* filesystem-illegal characters and may suffix collisions. For path-based work
|
|
52
|
+
* on a pulled folder, `docs push` is the right verb.
|
|
53
|
+
*/
|
|
54
|
+
async function resolveReplaceTarget(config, replace) {
|
|
55
|
+
if (/^\d+$/.test(replace)) {
|
|
56
|
+
return Number(replace);
|
|
57
|
+
}
|
|
58
|
+
const slash = replace.lastIndexOf('/');
|
|
59
|
+
const folderPath = slash === -1 ? undefined : replace.slice(0, slash);
|
|
60
|
+
const title = slash === -1 ? replace : replace.slice(slash + 1);
|
|
61
|
+
// A trailing slash ("marketing/") leaves no title to look up. Fail here rather
|
|
62
|
+
// than asking the server to resolve an empty title and reporting its 404.
|
|
63
|
+
if (title === '') {
|
|
64
|
+
console.error(chalk_1.default.red(`✗ --replace "${replace}" names a folder, not a doc`));
|
|
65
|
+
return process.exit(1);
|
|
66
|
+
}
|
|
67
|
+
try {
|
|
68
|
+
const params = {};
|
|
69
|
+
if (folderPath)
|
|
70
|
+
params.folder_path = folderPath;
|
|
71
|
+
params.title = title;
|
|
72
|
+
const response = await axios_1.default.get(`${config.host}/api/v1/docs/by-path`, {
|
|
73
|
+
params,
|
|
74
|
+
headers: (0, api_1.getApiHeaders)(config),
|
|
75
|
+
});
|
|
76
|
+
return response.data.doc.id;
|
|
77
|
+
}
|
|
78
|
+
catch (error) {
|
|
79
|
+
const status = error.response?.status;
|
|
80
|
+
const code = error.response?.data?.code;
|
|
81
|
+
if (status === 422 && code === 'folder_path_not_found') {
|
|
82
|
+
console.error(chalk_1.default.red(`✗ no folder "${folderPath}" in this workspace`));
|
|
83
|
+
}
|
|
84
|
+
else if (status === 404) {
|
|
85
|
+
console.error(chalk_1.default.red(`✗ no doc titled "${title}"${folderPath ? ` in "${folderPath}"` : ' at the docs root'}`));
|
|
86
|
+
}
|
|
87
|
+
else {
|
|
88
|
+
console.error(chalk_1.default.red(`✗ could not resolve "${replace}" — ${error.response?.data?.message ?? error.message}`));
|
|
89
|
+
}
|
|
90
|
+
return process.exit(1);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
46
93
|
/**
|
|
47
94
|
* Uploads one or more local files to SA-Docs media (`POST /api/v1/docs/media`),
|
|
48
95
|
* sequentially. `--title` is only valid for a single file — with multiple
|
|
@@ -53,6 +100,14 @@ async function docsUpload(files, options = {}) {
|
|
|
53
100
|
console.error(chalk_1.default.red('--title can only be used when uploading a single file.'));
|
|
54
101
|
process.exit(1);
|
|
55
102
|
}
|
|
103
|
+
if (options.replace && files.length > 1) {
|
|
104
|
+
console.error(chalk_1.default.red('--replace can only be used when uploading a single file.'));
|
|
105
|
+
process.exit(1);
|
|
106
|
+
}
|
|
107
|
+
if (options.replace && (options.title || options.folder)) {
|
|
108
|
+
console.error(chalk_1.default.red('--replace cannot be combined with --title or --folder — replace never renames or moves a doc.'));
|
|
109
|
+
process.exit(1);
|
|
110
|
+
}
|
|
56
111
|
const config = await (0, api_1.requireConfigWithWorkspace)();
|
|
57
112
|
let hadError = false;
|
|
58
113
|
for (const file of files) {
|
|
@@ -65,12 +120,20 @@ async function docsUpload(files, options = {}) {
|
|
|
65
120
|
}
|
|
66
121
|
const form = new form_data_1.default();
|
|
67
122
|
form.append('file', fs.createReadStream(absPath));
|
|
68
|
-
if (options.
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
123
|
+
if (!options.replace) {
|
|
124
|
+
if (options.folder)
|
|
125
|
+
form.append('folder_path', options.folder);
|
|
126
|
+
if (options.title)
|
|
127
|
+
form.append('title', options.title);
|
|
128
|
+
}
|
|
129
|
+
// Resolved once (--replace forbids multiple files), and kept so error messages
|
|
130
|
+
// can name the numeric doc id rather than echoing back a path.
|
|
131
|
+
const replaceDocId = options.replace ? await resolveReplaceTarget(config, options.replace) : null;
|
|
132
|
+
const url = replaceDocId !== null
|
|
133
|
+
? `${config.host}/api/v1/docs/${replaceDocId}/media`
|
|
134
|
+
: `${config.host}/api/v1/docs/media`;
|
|
72
135
|
try {
|
|
73
|
-
const response = await axios_1.default.post(
|
|
136
|
+
const response = await axios_1.default.post(url, form, {
|
|
74
137
|
headers: {
|
|
75
138
|
...form.getHeaders(),
|
|
76
139
|
...(0, api_1.getApiHeaders)(config),
|
|
@@ -78,10 +141,15 @@ async function docsUpload(files, options = {}) {
|
|
|
78
141
|
maxContentLength: Infinity,
|
|
79
142
|
maxBodyLength: Infinity,
|
|
80
143
|
});
|
|
81
|
-
// The 201 body nests the created doc under a `doc` key.
|
|
144
|
+
// The 201/200 body nests the created/updated doc under a `doc` key.
|
|
82
145
|
const doc = response.data?.doc;
|
|
83
|
-
|
|
84
|
-
|
|
146
|
+
if (options.replace) {
|
|
147
|
+
console.log(chalk_1.default.green(`✓ ${displayName} → doc ${doc?.id} (replaced, rev ${doc?.current_version_id})`));
|
|
148
|
+
}
|
|
149
|
+
else {
|
|
150
|
+
const location = doc?.folder_path || '/';
|
|
151
|
+
console.log(chalk_1.default.green(`✓ ${displayName} → ${location} (doc ${doc?.id})`));
|
|
152
|
+
}
|
|
85
153
|
}
|
|
86
154
|
catch (error) {
|
|
87
155
|
hadError = true;
|
|
@@ -93,6 +161,9 @@ async function docsUpload(files, options = {}) {
|
|
|
93
161
|
else if (status === 401) {
|
|
94
162
|
console.error(chalk_1.default.red(`✗ ${displayName} — Authentication failed. Run "solidactions login <api-key>" to re-configure.`));
|
|
95
163
|
}
|
|
164
|
+
else if (status === 404 && data?.code === 'media_not_found') {
|
|
165
|
+
console.error(chalk_1.default.red(`✗ ${displayName} — doc ${replaceDocId} is not a media doc`));
|
|
166
|
+
}
|
|
96
167
|
else if (status === 422) {
|
|
97
168
|
console.error(chalk_1.default.red(`✗ ${displayName} — ${(0, api_1.formatValidationError)(data)}`));
|
|
98
169
|
}
|
package/dist/index.js
CHANGED
|
@@ -623,8 +623,9 @@ docs
|
|
|
623
623
|
.description('Upload one or more media files to SA-Docs (requires a token with the "docs" ability)')
|
|
624
624
|
.option('--folder <path>', 'Folder path to upload into (auto-created if missing)')
|
|
625
625
|
.option('--title <title>', 'Title for the uploaded doc (only valid with a single file)')
|
|
626
|
+
.option('--replace <doc-id-or-path>', 'replace the bytes of an existing media doc (by id, or by docs path)')
|
|
626
627
|
.action(async (files, options) => {
|
|
627
|
-
await (0, docs_upload_1.docsUpload)(files, { folder: options.folder, title: options.title });
|
|
628
|
+
await (0, docs_upload_1.docsUpload)(files, { folder: options.folder, title: options.title, replace: options.replace });
|
|
628
629
|
});
|
|
629
630
|
program.parseAsync().catch((err) => {
|
|
630
631
|
console.error(chalk_1.default.red(err.message ?? String(err)));
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Sidecar manifest (`.solidactions-docs.json`) shared by `docs pull` and
|
|
4
|
+
* `docs push` to track which local files correspond to which SA-Docs docs,
|
|
5
|
+
* and to detect local/server drift via a body sha256.
|
|
6
|
+
*/
|
|
7
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
8
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
9
|
+
};
|
|
10
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
11
|
+
exports.DOCS_MANIFEST = void 0;
|
|
12
|
+
exports.sha256Hex = sha256Hex;
|
|
13
|
+
exports.readManifest = readManifest;
|
|
14
|
+
exports.writeManifest = writeManifest;
|
|
15
|
+
const fs_1 = __importDefault(require("fs"));
|
|
16
|
+
const path_1 = __importDefault(require("path"));
|
|
17
|
+
const crypto_1 = __importDefault(require("crypto"));
|
|
18
|
+
const chalk_1 = __importDefault(require("chalk"));
|
|
19
|
+
exports.DOCS_MANIFEST = '.solidactions-docs.json';
|
|
20
|
+
/** sha256 hex digest of the given bytes/string, as written to disk. */
|
|
21
|
+
function sha256Hex(data) {
|
|
22
|
+
return crypto_1.default.createHash('sha256').update(data).digest('hex');
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Read `<dir>/.solidactions-docs.json`. Absent or unparseable → null,
|
|
26
|
+
* meaning nothing under `dir` is guarded (sidecar convention).
|
|
27
|
+
*
|
|
28
|
+
* `docs push` warns on unparseable JSON (files silently becoming untracked would
|
|
29
|
+
* re-create every doc); `docs pull` stays silent (it is about to rewrite it anyway).
|
|
30
|
+
*/
|
|
31
|
+
function readManifest(dir, opts = {}) {
|
|
32
|
+
const manifestPath = path_1.default.join(dir, exports.DOCS_MANIFEST);
|
|
33
|
+
if (!fs_1.default.existsSync(manifestPath)) {
|
|
34
|
+
return null;
|
|
35
|
+
}
|
|
36
|
+
try {
|
|
37
|
+
return JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf8'));
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
if (opts.warnOnParseError) {
|
|
41
|
+
process.stderr.write(chalk_1.default.yellow(`warn: ${exports.DOCS_MANIFEST} exists but could not be parsed — all files will be treated as untracked\n`));
|
|
42
|
+
}
|
|
43
|
+
return null;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
function writeManifest(dir, manifest) {
|
|
47
|
+
fs_1.default.writeFileSync(path_1.default.join(dir, exports.DOCS_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
|
|
48
|
+
}
|