formist-cli 0.1.0__py3-none-any.whl

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.
formist_cli/uploads.py ADDED
@@ -0,0 +1,928 @@
1
+ """``fm upload`` / ``fm skill-attach``: files into a space, and skill attachments.
2
+
3
+ Two composable pieces, because they answer different questions:
4
+
5
+ * **`fm upload`** puts a local file into a project. It is a thin
6
+ client over the resumable upload route, never the one-shot
7
+ ``POST /files/upload`` (fine until the connection drops at 90%,
8
+ at which point the upload starts over from zero). The chunk PUT
9
+ is a raw byte body, which is also the one shape ``urllib`` can
10
+ send without this tool growing a multipart dependency.
11
+
12
+ * **`fm skill-attach`** registers an uploaded file on a skill's
13
+ ``Skill.files``, the only mechanism that survives workspace
14
+ export/import. Uploading a file and attaching it are genuinely
15
+ different acts (a File can exist without being any skill's
16
+ attachment), so this command does both, idempotently: it checks
17
+ whether the skill already resolves an attachment by this name,
18
+ using the same match rule the server uses at request time,
19
+ before doing anything, and uploads nothing when it already does.
20
+
21
+ Both commands write, so both take ``--env`` with no default (a write
22
+ must never inherit an environment) and both are a dry run unless
23
+ ``--apply`` is given, matching ``fm update``'s convention: the plan
24
+ prints first, and a second, explicit flag is required to act on it.
25
+
26
+ Stdlib only: this module must not add a runtime dependency.
27
+ """
28
+
29
+ from __future__ import annotations
30
+
31
+ import mimetypes
32
+ import re
33
+ import sys
34
+ import time
35
+ import unicodedata
36
+ from collections.abc import Callable
37
+ from pathlib import Path
38
+ from uuid import UUID
39
+
40
+ from formist_cli.targets import Target
41
+
42
+ # --- filename normalisation, kept in exact parity with the server -----------
43
+ #
44
+ # The server stores a File's `name` through its own `safe_filename`, and
45
+ # matches an attachment by running both sides through it before comparing
46
+ # case-insensitively. This client cannot import the server's version: it is
47
+ # stdlib-only, and the server module pulls in the whole SQLModel/FastAPI
48
+ # dependency tree. So this is a second, independent copy, pinned against the
49
+ # real function by a dedicated test so the two cannot drift silently.
50
+ _SAFE_NAME = re.compile(r"[^A-Za-z0-9._-]+")
51
+ _DISPLAY_FORBIDDEN = re.compile(r"[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069\ufeff]")
52
+ MAX_FILE_NAME_CHARS = 128
53
+
54
+
55
+ def safe_filename(name: str | None) -> str:
56
+ base = (name or "file").replace("\\", "/").rsplit("/", 1)[-1]
57
+ cleaned = _SAFE_NAME.sub("_", base).strip("._") or "file"
58
+ return cleaned[:128]
59
+
60
+
61
+ def display_filename(name: str | None) -> str:
62
+ """Same rule the server uses for a File's display name."""
63
+ base = unicodedata.normalize("NFC", name or "").replace("\\", "/").rsplit("/", 1)[-1]
64
+ base = _DISPLAY_FORBIDDEN.sub("", base).strip().strip(".").strip()
65
+ if not base:
66
+ return "file"
67
+ if len(base) > MAX_FILE_NAME_CHARS:
68
+ stem, dot, ext = base.rpartition(".")
69
+ if dot and stem and 0 < len(ext) <= 16:
70
+ base = f"{stem[: MAX_FILE_NAME_CHARS - len(ext) - 1].rstrip()}.{ext}"
71
+ else:
72
+ base = base[:MAX_FILE_NAME_CHARS].rstrip()
73
+ return base
74
+
75
+
76
+ def same_filename(candidate: str | None, wanted: str) -> bool:
77
+ """Same rule the server's runtime resolver uses to match an attachment."""
78
+ if not candidate:
79
+ return False
80
+ if display_filename(candidate).casefold() == display_filename(wanted).casefold():
81
+ return True
82
+ legacy = safe_filename(wanted)
83
+ return candidate == safe_filename(candidate) and "." in legacy and legacy.casefold() == candidate.casefold()
84
+
85
+
86
+ class UploadError(Exception):
87
+ """A file/attachment operation that could not proceed. Operator-facing."""
88
+
89
+
90
+ Caller = Callable[..., object]
91
+
92
+ DEFAULT_FOLDER_PATH = "/"
93
+
94
+ #: Chunk PUTs get a few attempts before giving up: the server's chunk-store
95
+ #: route is idempotent per index, so a blind retry after a dropped connection
96
+ #: is safe rather than merely convenient.
97
+ DEFAULT_CHUNK_RETRIES = 3
98
+ _RETRY_BACKOFF_SECONDS = 1.5
99
+
100
+
101
+ def _api():
102
+ # Imported lazily, same reasoning as formist_cli.resolve._default_fetch:
103
+ # this module stays importable, and its pure functions unit-testable
104
+ # with injected transports, without pulling in the HTTP layer.
105
+ from formist_cli import api
106
+
107
+ return api
108
+
109
+
110
+ def _maybe_uuid(value: object) -> str | None:
111
+ try:
112
+ UUID(str(value))
113
+ except (ValueError, TypeError, AttributeError):
114
+ return None
115
+ return str(value)
116
+
117
+
118
+ def _guess_content_type(filename: str) -> str:
119
+ guessed, _ = mimetypes.guess_type(filename)
120
+ return guessed or "application/octet-stream"
121
+
122
+
123
+ def _upload_prefix(space: str) -> str:
124
+ return f"/projects/{space}/files/upload"
125
+
126
+
127
+ # --- the resumable-session HTTP calls, one function per verb ----------------
128
+
129
+
130
+ def open_session(
131
+ target: Target,
132
+ space: str,
133
+ *,
134
+ token: str | None,
135
+ filename: str,
136
+ content_type: str,
137
+ total_size: int,
138
+ folder_path: str = DEFAULT_FOLDER_PATH,
139
+ owner: str | None = None,
140
+ task_id: str | None = None,
141
+ chunk_size: int | None = None,
142
+ relative_path: str | None = None,
143
+ post: Caller | None = None,
144
+ ) -> dict:
145
+ post = post or _api().post
146
+ body = {
147
+ "filename": filename,
148
+ "content_type": content_type,
149
+ "total_size": total_size,
150
+ "folder_path": folder_path,
151
+ "owner": owner,
152
+ "task_id": task_id,
153
+ "chunk_size": chunk_size,
154
+ # A folder drop's path inside the dropped folder: the same field a
155
+ # browser folder-drop sends (`webkitRelativePath`). The server
156
+ # derives the destination folder from this, so `fm upload DIR` never
157
+ # re-implements that join itself; it just states each file's path
158
+ # inside the directory and lets the server land it identically to
159
+ # the product's own folder-drop dialog.
160
+ "relative_path": relative_path,
161
+ }
162
+ result = post(target, f"{_upload_prefix(space)}/sessions", body, token=token)
163
+ if not isinstance(result, dict) or not result.get("upload_id"):
164
+ raise UploadError(f"open session returned an unexpected shape: {result!r}")
165
+ return result
166
+
167
+
168
+ def session_state(target: Target, space: str, upload_id: str, *, token: str | None, get: Caller | None = None) -> dict:
169
+ get = get or _api().get
170
+ result = get(target, f"{_upload_prefix(space)}/sessions/{upload_id}", token=token)
171
+ if not isinstance(result, dict):
172
+ raise UploadError(f"session state returned an unexpected shape: {result!r}")
173
+ return result
174
+
175
+
176
+ def put_chunk(
177
+ target: Target,
178
+ space: str,
179
+ upload_id: str,
180
+ index: int,
181
+ data: bytes,
182
+ *,
183
+ token: str | None,
184
+ put: Caller | None = None,
185
+ ) -> dict:
186
+ put = put or _api().put_bytes
187
+ path = f"{_upload_prefix(space)}/sessions/{upload_id}/chunks/{index}"
188
+ result = put(target, path, data, token=token)
189
+ if not isinstance(result, dict):
190
+ raise UploadError(f"chunk {index} PUT returned an unexpected shape: {result!r}")
191
+ return result
192
+
193
+
194
+ def _put_chunk_with_retry(
195
+ target: Target,
196
+ space: str,
197
+ upload_id: str,
198
+ index: int,
199
+ data: bytes,
200
+ *,
201
+ token: str | None,
202
+ put: Caller | None,
203
+ retries: int,
204
+ ) -> dict:
205
+ """Retry a chunk PUT on a transport failure, never on a 4xx (not transient).
206
+
207
+ The server re-checks the exact byte length on every chunk, so
208
+ re-sending the same index after a dropped connection is a no-op if
209
+ it already landed and a normal write if it did not, never a
210
+ duplicate.
211
+ """
212
+ api = _api()
213
+ last: Exception | None = None
214
+ for attempt in range(retries):
215
+ try:
216
+ return put_chunk(target, space, upload_id, index, data, token=token, put=put)
217
+ except api.ApiError as exc:
218
+ # A real refusal (bad chunk size, expired session, auth) will not
219
+ # change on retry; only a transport-layer failure might.
220
+ if getattr(exc, "status", None) is not None:
221
+ raise
222
+ last = exc
223
+ if attempt + 1 < retries:
224
+ time.sleep(_RETRY_BACKOFF_SECONDS * (attempt + 1))
225
+ raise UploadError(f"chunk {index} failed after {retries} attempts: {last}") from last
226
+
227
+
228
+ def complete_session(
229
+ target: Target, space: str, upload_id: str, *, token: str | None, post: Caller | None = None
230
+ ) -> dict:
231
+ post = post or _api().post
232
+ path = f"{_upload_prefix(space)}/sessions/{upload_id}/complete"
233
+ result = post(target, path, {}, token=token)
234
+ if not isinstance(result, dict) or not isinstance(result.get("item"), dict):
235
+ raise UploadError(f"complete returned an unexpected shape: {result!r}")
236
+ return result
237
+
238
+
239
+ def abort_session(
240
+ target: Target, space: str, upload_id: str, *, token: str | None, delete: Caller | None = None
241
+ ) -> None:
242
+ delete = delete or _api().delete
243
+ delete(target, f"{_upload_prefix(space)}/sessions/{upload_id}", token=token)
244
+
245
+
246
+ # --- the orchestration: local file -> a completed File row ------------------
247
+
248
+
249
+ def upload_file(
250
+ target: Target,
251
+ space: str,
252
+ file_path: Path,
253
+ *,
254
+ token: str | None,
255
+ folder_path: str = DEFAULT_FOLDER_PATH,
256
+ owner: str | None = None,
257
+ task_id: str | None = None,
258
+ content_type: str | None = None,
259
+ chunk_retries: int = DEFAULT_CHUNK_RETRIES,
260
+ relative_path: str | None = None,
261
+ on_chunk: Callable[[int, int], None] | None = None,
262
+ post: Caller | None = None,
263
+ put: Caller | None = None,
264
+ ) -> dict:
265
+ """Upload ``file_path`` via the resumable-session route. Returns the
266
+ completion response (``{"item": <File dict>, "audit_id": ...}``,
267
+ shape-identical to the one-shot route's).
268
+
269
+ Refuses a 0-byte source before opening a network connection: a
270
+ caller that uploads zero bytes and gets back a 200 is a real
271
+ failure mode, and the cheapest place to catch it is before any
272
+ bytes move. The size that actually landed is checked again
273
+ against the completion response at the end, for the same reason:
274
+ never trust what was sent, read back what arrived.
275
+
276
+ ``relative_path`` is this file's path inside a dropped directory
277
+ (see :func:`open_session`). ``fm upload DIR`` is the caller that
278
+ passes it, one file at a time, through this exact same per-file
279
+ path.
280
+ """
281
+ if not file_path.is_file():
282
+ raise UploadError(f"no such file: {file_path}")
283
+ total_size = file_path.stat().st_size
284
+ if total_size <= 0:
285
+ raise UploadError(f"{file_path} is empty (0 bytes); refusing to upload it")
286
+
287
+ filename = file_path.name
288
+ opened = open_session(
289
+ target,
290
+ space,
291
+ token=token,
292
+ filename=filename,
293
+ content_type=content_type or _guess_content_type(filename),
294
+ total_size=total_size,
295
+ folder_path=folder_path,
296
+ owner=owner,
297
+ task_id=task_id,
298
+ relative_path=relative_path,
299
+ post=post,
300
+ )
301
+ upload_id = opened["upload_id"]
302
+ chunk_size = opened["chunk_size"]
303
+ chunk_count = opened["chunk_count"]
304
+ already_received = set(opened.get("received_chunks") or [])
305
+
306
+ with file_path.open("rb") as fh:
307
+ for index in range(chunk_count):
308
+ start = index * chunk_size
309
+ length = min(chunk_size, total_size - start)
310
+ if index in already_received:
311
+ if on_chunk:
312
+ on_chunk(index, chunk_count)
313
+ continue
314
+ fh.seek(start)
315
+ data = fh.read(length)
316
+ if len(data) != length:
317
+ raise UploadError(
318
+ f"read {len(data)} bytes for chunk {index}, expected {length}; "
319
+ f"{file_path} changed size while it was being uploaded"
320
+ )
321
+ _put_chunk_with_retry(
322
+ target,
323
+ space,
324
+ upload_id,
325
+ index,
326
+ data,
327
+ token=token,
328
+ put=put,
329
+ retries=chunk_retries,
330
+ )
331
+ if on_chunk:
332
+ on_chunk(index, chunk_count)
333
+
334
+ completed = complete_session(target, space, upload_id, token=token, post=post)
335
+ item = completed["item"]
336
+ if item.get("size") != total_size:
337
+ raise UploadError(
338
+ f"uploaded, but the server's recorded size ({item.get('size')}) does not "
339
+ f"match the local file ({total_size} bytes); do not trust this File row "
340
+ f"(id={item.get('id')})"
341
+ )
342
+ return completed
343
+
344
+
345
+ # --- skill attachment: idempotent lookup + register --------------------------
346
+
347
+
348
+ def find_existing_attachment(
349
+ target: Target,
350
+ space: str,
351
+ skill: dict,
352
+ filename: str,
353
+ *,
354
+ token: str | None,
355
+ get: Caller | None = None,
356
+ ) -> dict | None:
357
+ """A File already registered on ``skill`` whose name matches ``filename``.
358
+
359
+ Mirrors the server's own matching exactly: a non-UUID ``files``
360
+ entry is a typed label, never an attachment, so it is skipped
361
+ rather than compared; a UUID entry that no longer resolves to a
362
+ file in this project is reported and skipped rather than treated
363
+ as a match or a fatal error, for the same reason the server-side
364
+ resolver treats it as absent and falls through. The name
365
+ comparison is the same rule the runtime resolver uses
366
+ (:func:`same_filename`), so "already attached" here means the
367
+ exact thing the server would resolve at request time, not a
368
+ separately invented guess at the question.
369
+ """
370
+ get = get or _api().get
371
+ for entry in skill.get("files") or []:
372
+ file_id = _maybe_uuid(entry)
373
+ if file_id is None:
374
+ continue
375
+ try:
376
+ file = get(target, f"/projects/{space}/files/{file_id}", token=token)
377
+ except Exception as exc: # 404 / network: treat as unresolvable, not fatal
378
+ print(
379
+ f" (skill {skill.get('id')} references file {file_id}, which could not be read: {exc})",
380
+ file=sys.stderr,
381
+ )
382
+ continue
383
+ if isinstance(file, dict) and same_filename(file.get("name"), filename):
384
+ return file
385
+ return None
386
+
387
+
388
+ def verify_file_size(
389
+ target: Target,
390
+ space: str,
391
+ file_id: str,
392
+ expected_size: int,
393
+ *,
394
+ token: str | None,
395
+ get: Caller | None = None,
396
+ ) -> dict:
397
+ """Independent proof that ``file_id`` really holds ``expected_size`` bytes.
398
+
399
+ A fresh GET, never a value this command already believes: not the
400
+ completion response just returned by the upload, not a size
401
+ printed a moment ago. Uploading zero bytes and getting back a 200
402
+ is a real failure mode, so this reads back what actually landed
403
+ rather than trusting what was sent, against the same row a caller
404
+ is about to report as good.
405
+ """
406
+ get = get or _api().get
407
+ file = get(target, f"/projects/{space}/files/{file_id}", token=token)
408
+ if not isinstance(file, dict) or not file.get("id"):
409
+ raise UploadError(f"could not read back file {file_id}; refusing to report success")
410
+ if file.get("size") != expected_size:
411
+ raise UploadError(
412
+ f"file {file_id} ({file.get('name')}) read back with size="
413
+ f"{file.get('size')}, expected {expected_size} bytes. Do not trust "
414
+ f"this attachment: it was read back and caught rather than assumed."
415
+ )
416
+ return file
417
+
418
+
419
+ def attach_file_to_skill(
420
+ target: Target,
421
+ space: str,
422
+ skill: dict,
423
+ file_id: str,
424
+ *,
425
+ token: str | None,
426
+ patch: Caller | None = None,
427
+ ) -> dict:
428
+ """PATCH the skill's ``files`` to include ``file_id``, preserving every
429
+ entry already there.
430
+
431
+ ``files`` is a plain list field, and a PATCH replaces whatever is
432
+ sent for a field that is present at all (only its absence is left
433
+ alone). Sending a bare ``[file_id]`` would silently drop every
434
+ attachment the skill already had. So this always starts from
435
+ ``skill["files"]``, read by the caller immediately beforehand,
436
+ never a value cached from an earlier step, and appends.
437
+ """
438
+ patch = patch or _api().patch
439
+ current = [str(f) for f in (skill.get("files") or [])]
440
+ if file_id in current:
441
+ # The id itself is already registered, not merely a same-named file.
442
+ # Re-sending an unchanged list would be a no-op PATCH; skip the write
443
+ # outright so a write that changes nothing does not look like one.
444
+ return skill
445
+ body = {"files": [*current, file_id]}
446
+ result = patch(target, f"/projects/{space}/skills/{skill['id']}", body, token=token)
447
+ item = result.get("item") if isinstance(result, dict) else None
448
+ if not isinstance(item, dict):
449
+ raise UploadError(f"attaching to the skill returned an unexpected shape: {result!r}")
450
+ return item
451
+
452
+
453
+ def resolve_skill(
454
+ name_or_id: str,
455
+ *,
456
+ target: Target,
457
+ space: str,
458
+ token: str | None,
459
+ fetch: Caller | None = None,
460
+ ) -> dict:
461
+ """The skill's full row, addressed by id or by name (exactly-one-or-refuse,
462
+ via ``formist_cli.resolve``, the same resolver ``fm get SKILL`` uses)."""
463
+ from formist_cli import resolve as resolve_mod
464
+
465
+ fetch = fetch or _api().get
466
+ file_id = _maybe_uuid(name_or_id)
467
+ skill_id = file_id
468
+ if skill_id is None:
469
+ match = resolve_mod.resolve_one(name_or_id, kind="SKILL", target=target, space=space, token=token, fetch=fetch)
470
+ skill_id = match.id
471
+ item = fetch(target, f"/projects/{space}/skills/{skill_id}", token=token)
472
+ if not isinstance(item, dict) or not item.get("id"):
473
+ raise UploadError(f"GET skill {skill_id} returned an unexpected shape: {item!r}")
474
+ return item
475
+
476
+
477
+ # --- `fm upload DIR`: every file under a directory, one resumable upload each ---
478
+ #
479
+ # Noise a directory drop should never treat as content. `__pycache__` is
480
+ # skipped as a whole directory (its contents are Python build artifacts,
481
+ # never source material an operator meant to upload); the other two are
482
+ # per-file OS litter.
483
+ _SKIPPED_UPLOAD_NAMES = frozenset({".DS_Store", "Thumbs.db", "__pycache__"})
484
+
485
+ #: How many paths a directory dry run lists before summarising the rest,
486
+ #: enough to sanity-check a batch without a large drop scrolling the
487
+ #: terminal.
488
+ DIR_DRY_RUN_PREVIEW = 20
489
+
490
+ #: The server refuses a 0-byte upload with 400 `empty-upload`, and
491
+ #: `upload_file` already refuses one locally before opening a socket (see
492
+ #: its docstring). A directory drop must not silently drop those rows from
493
+ #: the count or invent placeholder content to get them past the refusal.
494
+ #: This is just the label a directory upload's failure list uses so the
495
+ #: reason is legible without chasing the exception text.
496
+ EMPTY_FILE_REASON = "empty file (server refuses 0-byte uploads)"
497
+
498
+
499
+ def walk_upload_dir(root: Path) -> list[Path]:
500
+ """Every uploadable file under ``root``, recursively, in a stable
501
+ order (sorted, so a dry run and the ``--apply`` run right after it
502
+ describe and number the exact same sequence).
503
+
504
+ Skips :data:`_SKIPPED_UPLOAD_NAMES`: a bare filename match for the
505
+ two per-file entries, and any ``__pycache__`` directory pruned
506
+ entirely rather than merely having its own name checked (its
507
+ contents are never source material).
508
+ """
509
+ if not root.is_dir():
510
+ raise UploadError(f"no such directory: {root}")
511
+ out: list[Path] = []
512
+ for path in sorted(root.rglob("*")):
513
+ if not path.is_file():
514
+ continue
515
+ if path.name in _SKIPPED_UPLOAD_NAMES:
516
+ continue
517
+ if _SKIPPED_UPLOAD_NAMES.intersection(path.relative_to(root).parts[:-1]):
518
+ continue
519
+ out.append(path)
520
+ return out
521
+
522
+
523
+ def relative_upload_path(root: Path, file_path: Path) -> str:
524
+ """``file_path``'s path inside ``root``, forward-slash: the same
525
+ shape a browser folder-drop's ``webkitRelativePath`` sends, so the
526
+ server (not this client) computes the destination folder and a
527
+ directory upload lands subfolders exactly where the product's own
528
+ folder-drop dialog would.
529
+ """
530
+ return file_path.relative_to(root).as_posix()
531
+
532
+
533
+ def cmd_upload_dir(args) -> int:
534
+ """``fm upload DIR``: every file under DIR, each through the same
535
+ single-file resumable path :func:`cmd_upload` uses, via
536
+ ``relative_path`` (see :func:`open_session`) rather than a
537
+ client-side re-derivation of ``--folder-path`` per file.
538
+
539
+ Dry run lists what would be uploaded; ``--apply`` uploads every
540
+ file, never stopping at the first failure: a bulk drop that
541
+ aborted halfway would leave the operator unable to tell what
542
+ already landed from what did not, so every row is attempted and
543
+ the summary at the end says which failed and why. Exit code is
544
+ non-zero iff at least one file failed.
545
+ """
546
+ import json as json_mod
547
+
548
+ from formist_cli.cli import _effective, _token_for
549
+
550
+ eff = _effective(args, for_write=True)
551
+ token = _token_for(eff)
552
+ root = Path(args.file)
553
+ files = walk_upload_dir(root)
554
+ total_bytes = sum(f.stat().st_size for f in files)
555
+
556
+ if not args.apply:
557
+ print(
558
+ f"DRY RUN: nothing was changed.\n"
559
+ f"Would upload {len(files)} file(s), {total_bytes} bytes total, from "
560
+ f"{root} to space {eff.space} ({eff.target.name}), "
561
+ f"folder_path={args.folder_path!r}.",
562
+ file=sys.stderr,
563
+ )
564
+ for f in files[:DIR_DRY_RUN_PREVIEW]:
565
+ print(f" {relative_upload_path(root, f)} ({f.stat().st_size} bytes)", file=sys.stderr)
566
+ remaining = len(files) - DIR_DRY_RUN_PREVIEW
567
+ if remaining > 0:
568
+ print(f" ... and {remaining} more", file=sys.stderr)
569
+ print("To apply: re-run with --apply.", file=sys.stderr)
570
+ return 0
571
+
572
+ from formist_cli import api as api_mod
573
+
574
+ succeeded: list[str] = []
575
+ failed: list[tuple[str, str]] = []
576
+ for f in files:
577
+ rel = relative_upload_path(root, f)
578
+ if f.stat().st_size == 0:
579
+ print(f"FAILED {rel} {EMPTY_FILE_REASON}", file=sys.stderr)
580
+ failed.append((rel, EMPTY_FILE_REASON))
581
+ continue
582
+ try:
583
+ completed = upload_file(
584
+ eff.target,
585
+ eff.space,
586
+ f,
587
+ token=token,
588
+ folder_path=args.folder_path,
589
+ owner=args.owner,
590
+ task_id=args.task_id,
591
+ content_type=args.content_type,
592
+ relative_path=rel,
593
+ )
594
+ except (UploadError, api_mod.ApiError) as exc:
595
+ print(f"FAILED {rel} {exc}", file=sys.stderr)
596
+ failed.append((rel, str(exc)))
597
+ continue
598
+ item = completed["item"]
599
+ print(f"uploaded {rel} id={item['id']} size={item['size']}")
600
+ succeeded.append(rel)
601
+
602
+ if args.json:
603
+ print(
604
+ json_mod.dumps(
605
+ {
606
+ "root": str(root),
607
+ "uploaded": len(succeeded),
608
+ "failed": [{"path": rel, "reason": reason} for rel, reason in failed],
609
+ "total": len(files),
610
+ },
611
+ indent=2,
612
+ ensure_ascii=False,
613
+ )
614
+ )
615
+ print(
616
+ f"\n{len(succeeded)} uploaded, {len(failed)} failed, {len(files)} total",
617
+ file=sys.stderr,
618
+ )
619
+ if failed:
620
+ print("failed:", file=sys.stderr)
621
+ for rel, reason in failed:
622
+ print(f" {rel}: {reason}", file=sys.stderr)
623
+ return 1
624
+ return 0
625
+
626
+
627
+ # ===========================================================================
628
+ # The CLI surface. One `add_parser` per module: a line in cli.py per module,
629
+ # not a block.
630
+ # ===========================================================================
631
+
632
+
633
+ def add_parser(sub) -> None:
634
+ import argparse
635
+
636
+ from formist_cli.cli import _add_env, _add_space
637
+
638
+ p = sub.add_parser(
639
+ "upload",
640
+ help="upload a local file, or every file under a directory, into a space (resumable; WRITE)",
641
+ description=(
642
+ "Uploads FILE via the resumable-session route (open -> PUT chunks -> "
643
+ "complete), never the one-shot POST /files/upload, since that route "
644
+ "reads the whole body in one request, so a dropped connection on a "
645
+ "large file starts over from zero. This is a bare upload primitive: "
646
+ "it does not check whether a same-named file already exists (the "
647
+ "product UI upload button does not either). For registering a file "
648
+ "as a skill's template attachment, with that idempotence check, use "
649
+ "`fm skill-attach` instead.\n\n"
650
+ "When FILE is a DIRECTORY, every file under it is uploaded "
651
+ "recursively through this same per-file path, preserving subfolders "
652
+ "under --folder-path via `relative_path`, the identical field a "
653
+ "browser folder-drop sends, so the server lands the structure "
654
+ "exactly as the product's own dialog would. "
655
+ f"{', '.join(sorted(_SKIPPED_UPLOAD_NAMES))} are skipped. A 0-byte "
656
+ "file is refused by the server (400 empty-upload) and is reported "
657
+ "in the failure list rather than silently dropped or padded with "
658
+ "invented content. One file failing does not stop the rest; the "
659
+ "exit code is non-zero iff at least one failed.\n\n"
660
+ "DRY RUN by default: prints what would be sent and touches nothing. "
661
+ "--apply performs the upload(s)."
662
+ ),
663
+ formatter_class=argparse.RawDescriptionHelpFormatter,
664
+ )
665
+ _add_env(p, for_write=True)
666
+ _add_space(p)
667
+ p.add_argument("file", help="path to a local file, or a directory to upload recursively")
668
+ p.add_argument("--folder-path", default=DEFAULT_FOLDER_PATH)
669
+ p.add_argument("--owner", default=None, help="free-text team label")
670
+ p.add_argument("--task-id", default=None, help="attach the upload to a task (UUID)")
671
+ p.add_argument("--content-type", default=None, help="override the guessed MIME type (single file only)")
672
+ p.add_argument("--apply", action="store_true", help="perform the upload (default: dry run)")
673
+ p.add_argument("--json", action="store_true", help="machine-readable output")
674
+
675
+ p = sub.add_parser(
676
+ "skill-attach",
677
+ help="attach a local file to a skill as its template attachment (WRITE)",
678
+ description=(
679
+ "Registers FILE on SKILL's Skill.files, the mechanism the server "
680
+ "reads at runtime and the only one that survives workspace "
681
+ "export/import.\n\n"
682
+ "IDEMPOTENT: before doing anything, this reads the skill's current "
683
+ "attachments and checks each one against FILE's name using the "
684
+ "exact match rule the runtime resolver uses (safe_filename + "
685
+ "casefold). If the skill already resolves an attachment by this "
686
+ "name, nothing is uploaded and nothing is changed; the command "
687
+ "says so and exits 0.\n\n"
688
+ "SKILL is a skill id (UUID) or its exact name (resolved the same way "
689
+ "`fm get SKILL --name ...` does; refuses on more than one match).\n\n"
690
+ "DRY RUN by default: prints the plan (the skill's current attachments, "
691
+ "the file that would be uploaded, and the resulting files list) and "
692
+ "touches nothing. --apply performs the upload and the attach.\n\n"
693
+ "--file-id skips the upload and attaches an already-uploaded file "
694
+ "directly: the recovery path if a previous --apply uploaded "
695
+ "successfully but the attach step then failed (its file id is in that "
696
+ "run's output); this avoids uploading a second copy on retry."
697
+ ),
698
+ formatter_class=argparse.RawDescriptionHelpFormatter,
699
+ )
700
+ _add_env(p, for_write=True)
701
+ _add_space(p)
702
+ p.add_argument("skill", help="skill id (UUID) or exact name")
703
+ p.add_argument("file", help="path to a local file")
704
+ p.add_argument("--folder-path", default=DEFAULT_FOLDER_PATH)
705
+ p.add_argument("--owner", default=None, help="free-text team label")
706
+ p.add_argument(
707
+ "--file-id",
708
+ default=None,
709
+ help="attach this already-uploaded file id instead of uploading FILE again",
710
+ )
711
+ p.add_argument("--apply", action="store_true", help="perform the write (default: dry run)")
712
+ p.add_argument("--json", action="store_true", help="machine-readable output")
713
+
714
+
715
+ def _print_progress(index: int, count: int) -> None:
716
+ print(f" chunk {index + 1}/{count}", file=sys.stderr, end="\r")
717
+ if index + 1 == count:
718
+ print(file=sys.stderr)
719
+
720
+
721
+ def cmd_upload(args) -> int:
722
+ import json as json_mod
723
+
724
+ from formist_cli.cli import _effective, _token_for
725
+
726
+ if Path(args.file).is_dir():
727
+ return cmd_upload_dir(args)
728
+
729
+ eff = _effective(args, for_write=True)
730
+ token = _token_for(eff)
731
+ file_path = Path(args.file)
732
+
733
+ if not file_path.is_file():
734
+ print(f"error: no such file: {file_path}", file=sys.stderr)
735
+ return 2
736
+ size = file_path.stat().st_size
737
+ content_type = args.content_type or _guess_content_type(file_path.name)
738
+
739
+ if not args.apply:
740
+ print(
741
+ f"DRY RUN: nothing was changed.\n"
742
+ f"Would upload {file_path} ({size} bytes, {content_type}) as "
743
+ f"{file_path.name!r} to space {eff.space} ({eff.target.name}), "
744
+ f"folder_path={args.folder_path!r} owner={args.owner!r}"
745
+ f"{' task_id=' + args.task_id if args.task_id else ''}.\n"
746
+ f"To apply: re-run with --apply.",
747
+ file=sys.stderr,
748
+ )
749
+ return 0
750
+
751
+ completed = upload_file(
752
+ eff.target,
753
+ eff.space,
754
+ file_path,
755
+ token=token,
756
+ folder_path=args.folder_path,
757
+ owner=args.owner,
758
+ task_id=args.task_id,
759
+ content_type=args.content_type,
760
+ on_chunk=_print_progress,
761
+ )
762
+ item = completed["item"]
763
+ if args.json:
764
+ print(json_mod.dumps(completed, indent=2, ensure_ascii=False, default=str))
765
+ else:
766
+ print(f"uploaded: id={item['id']} name={item['name']} size={item['size']}")
767
+ print(f" web_url={item.get('web_url')}")
768
+ print(f" audit_id={completed.get('audit_id')}")
769
+ return 0
770
+
771
+
772
+ def cmd_skill_attach(args) -> int:
773
+ import json as json_mod
774
+
775
+ from formist_cli.cli import _effective, _token_for
776
+
777
+ eff = _effective(args, for_write=True)
778
+ token = _token_for(eff)
779
+ file_path = Path(args.file)
780
+ filename = file_path.name
781
+
782
+ skill = resolve_skill(args.skill, target=eff.target, space=eff.space, token=token)
783
+ print(
784
+ f" skill: {skill['id']} {skill.get('name')!r} "
785
+ f"({len(skill.get('files') or [])} existing attachment entr"
786
+ f"{'y' if len(skill.get('files') or []) == 1 else 'ies'})",
787
+ file=sys.stderr,
788
+ )
789
+
790
+ existing = find_existing_attachment(eff.target, eff.space, skill, filename, token=token)
791
+ if existing is not None:
792
+ print(
793
+ f"already attached, nothing to do.\n"
794
+ f" file: id={existing['id']} name={existing['name']} "
795
+ f"size={existing['size']}\n"
796
+ f" skill: id={skill['id']} name={skill.get('name')!r}"
797
+ )
798
+ # A same-named attachment already exists, but "the name resolves" is
799
+ # not "the bytes are right": the runtime resolver matches on name
800
+ # alone, so a truncated or stale attachment would pass this command's
801
+ # own idempotence check forever. When the local source is present,
802
+ # compare it. This does not block the operator (idempotence still
803
+ # means "do nothing"), but a live tool's continuity depends on this
804
+ # attachment, so a mismatch must be loud rather than silent.
805
+ if file_path.is_file():
806
+ local_size = file_path.stat().st_size
807
+ if existing.get("size") != local_size:
808
+ print(
809
+ f"size mismatch: the already-attached file is {existing.get('size')} "
810
+ f"bytes; the local source at {file_path} is {local_size} bytes. The "
811
+ f"attachment was NOT touched (that is what 'already attached' means), "
812
+ f"but this is worth investigating before relying on it: the local "
813
+ f"file may have been updated since the last attach, or the earlier "
814
+ f"upload may be incomplete.",
815
+ file=sys.stderr,
816
+ )
817
+ return 0
818
+
819
+ if not args.file_id and not file_path.is_file():
820
+ print(f"error: no such file: {file_path}", file=sys.stderr)
821
+ return 2
822
+
823
+ current_files = list(skill.get("files") or [])
824
+ if not args.apply:
825
+ if args.file_id:
826
+ plan = f"attach the already-uploaded file {args.file_id}"
827
+ else:
828
+ size = file_path.stat().st_size
829
+ plan = f"upload {file_path} ({size} bytes) as {filename!r}, then attach it"
830
+ print(
831
+ f"DRY RUN: nothing was changed.\n"
832
+ f"Skill {skill['id']} ({skill.get('name')!r}) has no attachment "
833
+ f"matching {filename!r}.\n"
834
+ f"Would {plan}.\n"
835
+ f" files: {len(current_files)} -> {len(current_files) + 1}\n"
836
+ f"To apply: re-run with --apply.",
837
+ file=sys.stderr,
838
+ )
839
+ return 0
840
+
841
+ if args.file_id:
842
+ file_dict = None
843
+ completed = None
844
+ else:
845
+ completed = upload_file(
846
+ eff.target,
847
+ eff.space,
848
+ file_path,
849
+ token=token,
850
+ folder_path=args.folder_path,
851
+ owner=args.owner,
852
+ on_chunk=_print_progress,
853
+ )
854
+ file_dict = completed["item"]
855
+
856
+ api = _api()
857
+ file_id = args.file_id or file_dict["id"]
858
+
859
+ # Independent read-back before attaching: a fresh GET, not the completion
860
+ # response `upload_file` already validated internally, and not the local
861
+ # `stat()` this command already trusts. Catching a bad upload here means
862
+ # a truncated file is never wired into the skill's resolution chain at
863
+ # all, even transiently.
864
+ if file_path.is_file():
865
+ verify_file_size(eff.target, eff.space, file_id, file_path.stat().st_size, token=token)
866
+ else:
867
+ readback_file = api.get(eff.target, f"/projects/{eff.space}/files/{file_id}", token=token)
868
+ if not isinstance(readback_file, dict) or not readback_file.get("id"):
869
+ raise UploadError(f"could not read back file {file_id}; refusing to attach it")
870
+ print(
871
+ f" (no local source at {file_path} to verify size against; file "
872
+ f"reads back as {readback_file.get('size')} bytes, unverified)",
873
+ file=sys.stderr,
874
+ )
875
+
876
+ try:
877
+ attach_file_to_skill(eff.target, eff.space, skill, file_id, token=token)
878
+ except Exception as exc:
879
+ if completed is not None:
880
+ print(
881
+ f"error: uploaded successfully but attaching to the skill failed: "
882
+ f"{exc}\n"
883
+ f"The file exists and is NOT attached: id={file_id} "
884
+ f"name={file_dict['name']} size={file_dict['size']}\n"
885
+ f"Re-run with --file-id {file_id} to attach it without "
886
+ f"uploading a second copy.",
887
+ file=sys.stderr,
888
+ )
889
+ raise
890
+
891
+ # Read back the skill independently of the PATCH response, from a fresh
892
+ # GET: never the local variable this command is about to confirm, and
893
+ # never only the mutation's own response body.
894
+ readback = api.get(eff.target, f"/projects/{eff.space}/skills/{skill['id']}", token=token)
895
+ readback_files = readback.get("files") if isinstance(readback, dict) else None
896
+
897
+ result = {
898
+ "skill": {"id": skill["id"], "name": skill.get("name")},
899
+ "file_id": file_id,
900
+ "files_before": current_files,
901
+ "files_after": readback_files,
902
+ "size_verified_by_fresh_read": file_path.is_file(),
903
+ }
904
+ if args.json:
905
+ print(json_mod.dumps(result, indent=2, ensure_ascii=False, default=str))
906
+ else:
907
+ print("attached.")
908
+ print(
909
+ " size verified by an independent read-back before attaching."
910
+ if file_path.is_file()
911
+ else " size NOT verified against a local source (see the read-back note above)."
912
+ )
913
+ print(f" skill: id={skill['id']} name={skill.get('name')!r}")
914
+ print(
915
+ f" file: id={file_id}"
916
+ + (
917
+ f" name={file_dict['name']} size={file_dict['size']} web_url={file_dict.get('web_url')}"
918
+ if file_dict
919
+ else ""
920
+ )
921
+ )
922
+ print(f" files: {len(current_files)} -> {len(readback_files) if isinstance(readback_files, list) else '?'}")
923
+ print(
924
+ f" to undo by hand: PATCH the skill's files back to {current_files!r}; "
925
+ f"the uploaded File row (id={file_id}) can be deleted separately if "
926
+ f"nothing else references it."
927
+ )
928
+ return 0