@tinycloud/cli 1.3.0-beta.43 → 1.3.0-beta.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinycloud/cli",
-  "version": "1.3.0-beta.43",
+  "version": "1.3.0-beta.44",
   "description": "TinyCloud CLI - manage data, delegations, and nodes from the terminal",
   "author": "TinyCloud, Inc.",
   "license": "EGPL",

package/skills/tc-cli/REFERENCE.md

@@ -392,6 +392,8 @@ Versions are kept by default and count against the owner's storage. The node doe
 
 The fragment after `#` is the read key. Browsers never send it to a server; `--notify` gives the link to TinyCloud only to email your recipients. Keep complete URLs out of logs. Human publish output is exactly one URL. JSON publish output never contains the link: it retains the redacted publication fields (including the share id) and adds `notification` (the `ShareNotifyResult`, including `state`, `attempts`, and optional failure `reason`) when `--notify` was requested. To get the complete link after a `--json` publish, run `tinycloud share show <id> --reveal-link`, ideally writing it straight to a private file. Inspect never prints plaintext or secret-bearing fields. Receive uses a sanitized single-segment filename and refuses overwrite unless `--force`. `revoke` asks the owner node to revoke the share (an addressed share's Policy/v3 root, or a bearer link's delegation) and reports `revoked` only when the node confirms it; receiving the link then fails; for a bearer link, `tinycloud share receive` reports `SHARE_REVOKED` (exit 4, "This share link has been revoked by its sender."). Revoking an already revoked share keeps its original `revokedAt`. A bearer revoke that cannot proceed revokes nothing: `SHARE_ISSUER_KEY_UNAVAILABLE` (exit 5) when this profile cannot sign for the link, `SHARE_LINK_UNAVAILABLE` (exit 4) when the stored link is missing or does not match the record, and `SHARE_REVOKE_REJECTED` (exit 4, with the node's reason) when the node refuses. `SHARE_REVOKE_UNCONFIRMED` (exit 1) means the node answered without confirming: the link may already be revoked, history is not marked revoked, and you should check whether the link still opens before retrying. Pre-cutover blob-backed and plaintext `?tc2` links are not accepted.
 
+**Publish history status.** `share publish --json` reports the sender-history write as `history`: `{"recorded": true}` when the share was saved, or `{"recorded": false, "reason": "<CODE>"}` when it was not. `HISTORY_UNREADABLE` means the existing history file cannot be decrypted or parsed with the current session key. `HISTORY_READ_FAILED` means the filesystem refused or failed to read that file. `HISTORY_WRITE_FAILED` means a filesystem or permission error during the write. `HISTORY_UNAVAILABLE` covers every other failure, including a profile-lock timeout. The exit status is 0 in all four cases, so do not retry the publish on this result: a retry creates a duplicate share. The stderr warning names the reason and the share id and CID to keep. It never includes the link, the key, or ciphertext. When `--notify` delivers but the delivery confirmation cannot be saved, `history.recorded` stays `true` (the share itself was saved) and the warning names the reason, the share id, and the CID.
+
 **Notification window.** The CLI requests a stable signed delivery authorization until the earlier of share expiry and 5 minutes after its sender-history `registeredAt` timestamp. The node allows an authorization no more than 5 minutes in the future; keeping the expiry stable also makes idempotent retries use the same request. After the window, `tinycloud share notify` prints `partial-failure` (exit 9; JSON `retryable: false`, `reason: "delivery-window-expired"`) and explains that the sender must publish a new share and invite the recipient then. `share publish --notify --json` includes the same failure under `notification`. A confirmed repeat within the window prints `already-delivered`; an unconfirmed failed attempt remains retryable until the window closes. If the sender history cannot record a successful delivery confirmation, the CLI warns on stderr but preserves the successful publish/notify result; a later repeat can report `delivered` again.
 
 **History and node preflight.** Post-publication sender-history writes wait up to 45 seconds for another process's profile lock (including stale-lock recovery). If the first history write still fails, the CLI warns and keeps its normal exit status: human output still prints the published link, but `--json` output stays redacted, and because the share was not recorded, `share show <id> --reveal-link` cannot recover it either. A later `share list`, `share notify <id>`, or `share revoke <id>` cannot find that share by ID. An immediate `--notify` can still deliver using the in-process record. Other share-command profile-lock timeouts report `PROFILE_LOCK_TIMEOUT` with a retry hint. Standalone domain notification validates the recipient and expired delivery window locally before contacting `/info`: an expired window remains exit 9 even if the node is unavailable. A node-info transport failure, including a stalled response body, is `UNAVAILABLE` (exit 4); a completed but unsupported or malformed version is `INVALID_ARGUMENT` (exit 2). Publish-time refusals say nothing was shared and no invitation was sent; standalone notify refusals say no invitation was sent.