@solidactions/cli 1.29.0 → 1.31.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 CHANGED
@@ -150,10 +150,19 @@ Manage agent skills on the crews SOP surface. `push` is an idempotent upsert (cr
150
150
  | `skill view <name>` | `--json` | Show one skill |
151
151
  | `skill pull <name> [dest]` | `--json` | Fetch a skill to a local folder for editing (inverse of push); writes a `.solidactions-skill.json` provenance sidecar used by `push`'s drift guard |
152
152
  | `skill delete <name>` | `--json` | Delete a skill (Admin only) |
153
- | `skill run <dir> -- <command...>` | `--crew <nameOrId>`, `--environment <env>` (default `dev`), `--env-file <path>` | Run a skill script LOCALLY with crew variables fetched from the platform (dev loop). Secret values need a token with `env:reveal`; see `skill exec` for the remote/deployed counterpart |
154
- | `skill exec <name> -- <command...>` | `--role <name>`, `--in-crew <crew>`, `--environment <env>` (default `production`) | Run a command against the DEPLOYED skill in its real sandbox runtime (post-push smoke); see `skill run` for the local dev-loop counterpart |
153
+ | `skill exec <name> --target sandbox -- <cmd>` (`--target` required) | `--role <name>`, `--in-crew <crew>`, `--environment <env>` (default `production`) | Execute the server-stored skill in its server sandbox (post-push smoke; default env production) |
154
+ | `skill exec <name> --target host -- <cmd>` (`--target` required) | `--role <name>`, `--in-crew <crew>`, `--crew <nameOrId>`, `--environment <env>` (default `production`), `--env-file <path>` | Execute the server-stored skill on THIS machine via a transparent revision-checked cache — no pull step; crew vars fetched from the platform (default env production; secrets need `env:reveal`) |
155
+ | `skill dev <dir> -- <cmd>` | `--crew <nameOrId>`, `--environment <env>` (default `dev`), `--env-file <path>` | Run your local working copy (the folder you're editing) with platform crew vars (default env dev). Replaces `skill run` (deprecated) |
155
156
 
156
- For `skill run` / `skill exec`, pass the command as separate words after `--` (e.g. `-- python script.py --flag`); to run a single preformed shell string, wrap it explicitly with `sh -c '...'`.
157
+ `skill exec` always executes the **server-stored** skill — `--target` only picks
158
+ where it runs (`sandbox` = server, `host` = your machine, cached under
159
+ `~/.solidactions/cache/skills/`, refreshed automatically when the skill's
160
+ published revision changes). `skill dev` always runs the **folder you're
161
+ editing**. Passing a directory to `exec` or a bare name to `dev` is an error
162
+ that points at the right command. Both `exec` targets default to `production`
163
+ variables; `dev` defaults to `dev`.
164
+
165
+ For `skill dev` / `skill exec`, pass the command as separate words after `--` (e.g. `-- python script.py --flag`); to run a single preformed shell string, wrap it explicitly with `sh -c '...'`.
157
166
 
158
167
  ### role
159
168
 
@@ -168,12 +177,27 @@ Manage docs in SA-Docs (the app's built-in documentation vault). `push` is drift
168
177
  | Command | Key Flags | Description |
169
178
  |---------|-----------|-------------|
170
179
  | `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` | Upload one or more media files to SA-Docs (requires a token with the "docs" ability); `--title` only valid for a single file |
180
+ | `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`) |
181
+ | `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 |
182
+
183
+ `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:
184
+
185
+ ```bash
186
+ solidactions docs upload logo-v2.png --replace 482
187
+ solidactions docs upload logo-v2.png --replace marketing/logo.png
188
+ ```
189
+
190
+ **`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.
191
+
192
+ **`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`).
193
+
194
+ 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.
195
+
196
+ **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.
173
197
 
174
- Deletions don't propagate: a doc removed on the server still exists locally after a re-pull, and an untracked `push` can re-create it — remove the local file yourself.
198
+ **`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.
175
199
 
176
- **`docs pull --overwrite` is destructive.** If any manifest-tracked file's local content 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. `-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`).
200
+ **`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
201
 
178
202
  ### workspace
179
203
 
@@ -3,23 +3,25 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.formatValue = formatValue;
6
7
  exports.crewEnvList = crewEnvList;
7
8
  const axios_1 = __importDefault(require("axios"));
8
9
  const chalk_1 = __importDefault(require("chalk"));
9
10
  const api_1 = require("../utils/api");
10
11
  const crew_1 = require("../utils/crew");
11
12
  /**
12
- * Format a value for display. Secrets are ALWAYS masked with a fixed
13
- * placeholder — regardless of what the server sent — so a server-side
14
- * masking bug can never leak a raw secret into stdout.
13
+ * Format a value for display. A null/undefined value means the env is
14
+ * unset and always renders as '-'. Otherwise, a secret's value is ALWAYS
15
+ * masked with a fixed placeholder — regardless of what the server sent —
16
+ * so a server-side masking bug can never leak a raw secret into stdout.
15
17
  */
16
18
  function formatValue(value, isSecret) {
17
- if (isSecret) {
18
- return chalk_1.default.yellow('••••••');
19
- }
20
19
  if (value === null || value === undefined) {
21
20
  return chalk_1.default.gray('-');
22
21
  }
22
+ if (isSecret) {
23
+ return chalk_1.default.yellow('••••••');
24
+ }
23
25
  return value.substring(0, 18);
24
26
  }
25
27
  async function crewEnvList(crewArg, options = {}) {
@@ -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
- if (!fs_1.default.existsSync(absPath))
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
- * 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).
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 writeDocs(destination, docs, config) {
246
- const manifestDocs = {};
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
- fs_1.default.writeFileSync(path_1.default.join(dirAbs, fileName), media.bytes);
289
- files.push({ path: relPath, action: 'written' });
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; skip the write but
294
- // still record the manifest entry below so the doc isn't silently lost.
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
- 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);
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: media.isMedia,
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, warnings };
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, warnings } = await writeDocs(destination, fetched, config);
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
- fs_1.default.writeFileSync(path_1.default.join(destination, exports.DOCS_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
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
  /**