@aefree/pi-plastic 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project follows semantic versioning for public package releases.
 
 ## Unreleased
 
+## [0.6.1] - 2026-09-14
+
+### Fixed
+
+- Clarify that `cm cat --file` writes to and can overwrite its destination, including when stdout is redirected. Route ordinary baseline reviews through typed diff tools, require new external temporary destinations for necessary manual exports, and distinguish changeset numbers from file revision IDs.
+
 ## [0.6.0] - 2026-09-14
 
 ### Added

package/README.md

@@ -111,13 +111,13 @@ pi install npm:@aefree/pi-plastic
 Install a pinned GitHub release over HTTPS:
 
 ```bash
-pi install git:github.com/aefreedman/pi-plastic@v0.6.0
+pi install git:github.com/aefreedman/pi-plastic@v0.6.1
 ```
 
 Equivalent SSH install:
 
 ```bash
-pi install git:git@github.com/aefreedman/pi-plastic@v0.6.0
+pi install git:git@github.com/aefreedman/pi-plastic@v0.6.1
 ```
 
 To intentionally track the moving default branch instead of a release tag:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-plastic",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"

package/skills/using-plastic/SKILL.md

@@ -10,6 +10,8 @@ Purpose: PlasticSCM operations for Unity workflows.
 
 Never run `cm diff` in Pi. It may launch GUI windows and block the CLI agent.
 
+`cm cat --file=<path>` writes to that path and can overwrite existing files; `--file` is never an input selector. Never point it at a canonical workspace file during inspection or review, even when piping stdout elsewhere. Use typed diff tools for baseline comparisons. If a typed tool cannot represent a required export, read the [historical export rules](references/changeset-operations.md#historical-export-fallback) first. A changeset number is not a file revision ID; never turn `cs:<number>` into `revid:<number>`.
+
 Never run interactive `cm merge --merge` flows. Use `plastic_merge` (preferred) or explicitly pass `--nointeractiveresolution --mergetype=try` (safe default). Use source/destination policy flags only as explicit overrides.
 
 Treat `plastic_merge` success as provisional until `plastic_status` confirms there are no merge-in-progress hints. Pending merge links are expected until the merge result is checked in; merge-in-progress hints are not. If files are manually resolved and validated but checkin is blocked by Plastic merge metadata, use `plastic_finalizeMerge` with an explicit source/destination policy before retrying checkin.

package/skills/using-plastic/references/changeset-operations.md

@@ -84,6 +84,20 @@ plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevisio
 
 The typed diff tools own historical `cm cat --file` materialization and cleanup; do not create agent-authored temporary files for ordinary diffs. `cm cat --raw` is unsupported for this workflow. Use typed retrieval first; `cm cat --file` is the byte-preserving low-level fallback only when a typed tool cannot represent the case.
 
+## Historical Export Fallback
+
+Use this fallback only when typed retrieval cannot represent the required case. For an ordinary workspace-base comparison, omit `revision` from `plastic_diffFile`; for a changeset comparison, supply its `revision="cs:<number>"` argument.
+
+`cm cat <revspec> --file=<output-file>` writes historical bytes to the output file and can overwrite it. `--file` does not select the source. Piping this command to `Set-Content` or redirecting stdout does not change the destination or protect it: with `--file`, the file contents are written there rather than to stdout.
+
+Before a necessary manual export:
+
+- Verify the source selector. `revid:<id>` means an actual file revision ID, not a workspace changeset number. Use a verified repository/server-qualified revision ID, or a file-qualified `<path>#cs:<number>` selector for a file at a changeset.
+- Create a new unique temporary directory outside the workspace and select a new absolute output path within it. Confirm that the destination does not exist. Never use a canonical workspace path or an existing baseline as the export destination.
+- Export directly to that temporary destination; do not combine `--file` with a stdout pipeline to capture the content. Check command success and the exported content before comparison. Keep comparison baselines immutable.
+
+If an export overwrites a workspace file, stop further exports and edits, record the exact command and destination, and inspect pending status. A clean status after exporting base revisions can mean pending work was erased; it does not prove successful review. Report the incident before attempting recovery, and preserve unrelated user changes.
+
 ## Commit Message Format
 
 Use conventional commits from ../../_shared/references/conventional-commits.md.

package/skills/using-plastic/references/reviewing-changes.md

@@ -33,6 +33,8 @@ plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevisio
 
 The diff tools materialize historical bytes and remove their temporary files internally. Added and explicitly selected private/new files use an empty base; an added empty file is reported as `added-empty`, not generic unchanged. Changed, moved, and deleted records use their status revision ID when available. A `--nodata` item cannot supply historical/base bytes: refresh the workspace or use two known file-qualified revisions. `plastic_workspaceDiff` requires selected paths or `allPending=true` and returns per-file unavailable outcomes instead of aborting the batch. Text-diff tools use bounded GNU/POSIX text diff, materialize backend operands to ASCII-safe package paths while preserving logical Unicode output labels, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review. `cm cat --raw` is unsupported in this workflow; typed retrieval owns cleanup, and `cm cat --file` is the byte-preserving low-level fallback only when needed.
 
+`cm cat --file` is a filesystem write: its argument is the output destination, never the source file. Pointing it at a working file overwrites pending changes even if stdout is piped to a temporary file. Reviewers must use typed comparisons for ordinary baseline review; a necessary unsupported export must follow the [historical export rules](changeset-operations.md#historical-export-fallback), with a new absolute temporary destination outside the workspace and a verified file revision selector.
+
 ## Metadata Listing (No GUI Diff)
 
 Use changeset metadata to understand branch activity: