@aefree/pi-plastic 0.4.0

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

@@ -0,0 +1,71 @@
+# Reviewing Changes
+
+## Critical Rule
+
+Never run `cm diff` in Pi. It may open a GUI window and block CLI automation.
+
+`plastic_diff` is disabled by design.
+
+## Focused Patch Generation
+
+Use `plastic_patch` when you need a branch-review patch for AI assistance, code review, or sharing outside the Plastic GUI:
+
+```text
+plastic_patch(source="<branch-spec>", integration=true)
+plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")
+plastic_patch(source="<left-spec>", destination="<right-spec>")
+plastic_patch(source="<branch-spec>", toolPath="<path-to-diff-tool>")
+```
+
+`integration=true` shows changes pending merge into the parent branch. `clean=true` strips content that arrived via merges. Use `output` for large patches; Plastic refuses to overwrite an existing output file. Inspect patch contents before sharing because patches can contain source code, binary data, local paths, or secrets present in changed files.
+
+## Text-Only Diff Options
+
+Prefer tool-first:
+
+```text
+plastic_status(machineReadable=true) # “what changed?” / changed-path listing
+plastic_diffFile(path="<workspace-path>") # common workspace vs Plastic-base comparison
+plastic_diffFile(path="<workspace-path>", revision="cs:<number>") # explicit advanced comparison
+plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
+```
+
+The diff tools materialize historical bytes and remove their temporary files internally. They use a bounded portable text diff, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review.
+
+## Metadata Listing (No GUI Diff)
+
+Use changeset metadata to understand branch activity:
+
+```bash
+cm find changeset "where branch = '<branch-name>' order by changesetid desc limit 20" --format="{changesetid} {owner} {date} {comment}" --nototal
+```
+
+## Read Files Directly
+
+Use the Read tool for full context instead of GUI diffs.
+
+## CLI-Safe File Diff
+
+Use the common no-revision path first; `base`, `head`, and `cs:head` are rejected rather than guessed:
+
+```text
+plastic_diffFile(path="<workspace-path>")
+plastic_diffFile(path="<workspace-path>", revision="br:/<branch>")
+plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
+```
+
+## Pending Changes
+
+Prefer tool-first:
+
+```text
+plastic_status()
+```
+
+Manual shell fallback:
+
+```bash
+cm status --all
+```
+
+When pending changes include deletions, verify deleted paths in status output before checkin.

package/skills/using-plastic/references/shelving.md

@@ -0,0 +1,25 @@
+# Shelving
+
+## Save Work
+
+```bash
+cm shelveset create -c="Working on feature X"
+```
+
+## List Shelves
+
+```bash
+cm find shelve "where owner='me'" --format="{shelveid} {date} {comment}"
+```
+
+## Restore Work
+
+```bash
+cm shelveset apply sh:5
+```
+
+## Delete Shelve
+
+```bash
+cm shelveset delete sh:5
+```

package/skills/using-plastic/references/troubleshooting.md

@@ -0,0 +1,115 @@
+# Troubleshooting
+
+## Branch Already Exists
+
+```bash
+cm find branch "where name='<branch-name>'"
+```
+
+## Cannot Switch (Pending Changes)
+
+```bash
+cm shelveset create --all -c="Auto-save before switch"
+cm switch --silent --noinput <branch-spec>
+```
+
+- In unattended mode, `pendingChanges="bring"` is blocked only when tracked pending changes exist.
+- Private-only pending changes do not require interactive bring; `plastic_switchBranch` now performs a direct switch.
+- `pendingChanges="shelve"` may report `There are no changes in the workspace` when pending items are private-only;
+  the tool recovers by skipping shelve and switching directly.
+
+Agent preference: use runtime `plastic_*` methods first; keep shell commands as manual fallback.
+
+## Code Review Creation Failed
+
+- Use GUI or document changeset in plan/issue tracker.
+
+## Reviewer Not Assigned
+
+- Reviewer assignment is required for code review workflow.
+- Preferred: gather branch/status via `plastic_status()` first, then assign reviewer in review edit flow.
+- Shell fallback:
+
+```bash
+cm codereview -e <review-id> --reviewer="reviewer-name"
+```
+
+- If the reviewer flag differs in your server, use `cm codereview --help` and apply the equivalent reviewer option.
+
+## GUI Opens When Using cm diff
+
+- `cm diff` is blocked in Pi because it can launch GUI windows and hang the CLI.
+- Use text-only alternatives:
+  - `plastic_status(machineReadable=true)` for changed paths/statuses.
+  - `plastic_diffFile(path="<workspace-path>")` for the common workspace-base comparison.
+  - `plastic_diffFile(path="<workspace-path>", revision="cs:<number>")` for an explicit supported revision.
+  - `plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")` for two historical files.
+
+## GUI/Prompt Opens During Merge
+
+- Do not run interactive `cm merge --merge` in Pi.
+- Preferred:
+
+```text
+plastic_merge(source="<source-branch-spec>")
+```
+
+- Shell fallback must be non-interactive and use safe auto-resolution:
+
+```bash
+cm merge <source-branch-spec> --merge --nointeractiveresolution --mergetype=try
+```
+
+- Explicit override (only when intentional):
+
+```text
+plastic_merge(source="<source-branch-spec>", strategy="destination")
+plastic_merge(source="<source-branch-spec>", strategy="source")
+```
+
+- If Plastic reports a delete/change directory conflict and you intentionally want to accept the source-side deletion, use:
+
+```text
+plastic_resolveDeleteChangeConflict(paths=["<workspace-path>"], keepOnDisk=true)
+```
+
+- Then rerun `plastic_merge(...)`.
+- Even when `plastic_merge(...)` reports success, run `plastic_status()` before checkin. Merge output is not authoritative if Plastic still reports merge state.
+
+## Merge Checkin Says Merge Is Still In Progress
+
+- Symptom:
+  - `plastic_merge(...)` reports `FILE_CONFLICT` paths or checkin later fails with a merge-in-progress error.
+  - The files have been reviewed/resolved and compile/tests pass.
+  - `plastic_status()` still shows pending merge metadata.
+- Treat `plastic_status()` merge-state hints as the source of truth. Pending merge links are expected until checkin; explicit merge-in-progress hints are blockers.
+- Recovery flow:
+  1. Run `plastic_status()` and inspect merge-state details plus any `FILE_CONFLICT` paths reported by `plastic_merge(...)`.
+  2. Resolve/review the listed files manually and run compile/tests as appropriate.
+  3. Run `plastic_finalizeMerge(source="<source-branch-spec>", strategy="destination")` to finalize Plastic merge metadata while preserving the reviewed destination/manual result. Use `strategy="source"` only when accepting source is intentional.
+  4. Run `plastic_status()` again.
+  5. Retry `plastic_checkin(...)` after merge-in-progress hints are gone.
+- If you are unsure whether the reviewed workspace result will be preserved, create a shelveset before finalizing.
+
+## Invalid cm diff --summary Usage
+
+- Do not use `cm diff --summary`; this form is invalid.
+- Also avoid all other `cm diff` forms in Pi.
+- Use the same text-only alternatives listed above.
+
+## Deleted Files Missing From Checkin
+
+- Run `cm status --all` and confirm deleted items are listed before checkin.
+- Use `plastic_checkin(preflight=true, paths=[...])` first; the tool can auto-rewrite moved/deleted file scopes to parent directories.
+- If a path-scoped checkin is rejected as "not changed", rerun with `applyChanged=true` and a parent-directory scope.
+- Re-run `cm status --all` just before checkin to validate scope.
+
+## Checkin says "No changes" but files were expected
+
+- `includeAll=true` does not include private items automatically.
+- `plastic_checkin` now pre-checks machine-readable status and can auto-add safe private files in scope,
+  then retry checkin once when Plastic returns `There are no changes in the workspace`.
+- If only sensitive private paths are found (for example `.env*`, key material, `.npmrc`, credentials/secrets JSON),
+  auto-add is blocked and the tool returns an actionable error requiring explicit add/include choice.
+- Check JSON metadata fields (`decisionPath`, `prePendingSummary`, `postPendingSummary`, `autoAddedPrivatePaths`,
+  `blockedPrivateAutoAddPaths`) to understand what unattended recovery path was used.

package/skills/using-plastic/references/workspaces.md

@@ -0,0 +1,33 @@
+# Review Workspaces
+
+## Strategy
+
+- Use a separate review workspace for isolation.
+- Reuse `-review-1` by default (Unity workspaces are large).
+
+## Create or Reuse
+
+```bash
+main_workspace=$(basename "$PWD")
+review_workspace_name="${main_workspace}-review-1"
+review_workspace="../${review_workspace_name}"
+
+if [ -d "$review_workspace" ]; then
+  cd "$review_workspace"
+  cm switch --silent --noinput "$review_branch" || {
+    cm shelveset create --all -c="Auto-shelve before review switch"
+    cm switch --silent --noinput "$review_branch"
+  }
+else
+  repo_spec=$(cm status --wkconfig | grep "^Repository:" | cut -d: -f2- | xargs)
+  cm workspace create "$review_workspace_name" "$review_workspace" "$repo_spec"
+  cd "$review_workspace"
+  cm switch --silent --noinput "$review_branch"
+fi
+```
+
+Agent preference: use runtime `plastic_*` methods first for branch/status operations; keep shell commands as manual fallback.
+
+## Cleanup
+
+Only remove review workspaces when disk space is tight or requested.

package/src/pi-tool-compat.ts

@@ -0,0 +1,56 @@
+type SchemaNode = {
+  kind: string;
+  values?: unknown;
+  inner?: unknown;
+  metadata?: Record<string, unknown>;
+  optional(): SchemaNode;
+  describe(description: string): SchemaNode;
+  min(value: number): SchemaNode;
+  max(value: number): SchemaNode;
+  int(): SchemaNode;
+};
+
+function createSchemaNode(kind: string, values?: unknown, inner?: unknown): SchemaNode {
+  const node: SchemaNode = {
+    kind,
+    values,
+    inner,
+    metadata: {},
+    optional() {
+      this.metadata = { ...(this.metadata ?? {}), optional: true };
+      return this;
+    },
+    describe(description: string) {
+      this.metadata = { ...(this.metadata ?? {}), description };
+      return this;
+    },
+    min(value: number) {
+      this.metadata = { ...(this.metadata ?? {}), min: value };
+      return this;
+    },
+    max(value: number) {
+      this.metadata = { ...(this.metadata ?? {}), max: value };
+      return this;
+    },
+    int() {
+      this.metadata = { ...(this.metadata ?? {}), int: true };
+      return this;
+    },
+  };
+  return node;
+}
+
+export const tool = Object.assign(
+  <T extends Record<string, unknown>>(definition: T): T => definition,
+  {
+    schema: {
+      string: () => createSchemaNode("string"),
+      number: () => createSchemaNode("number"),
+      boolean: () => createSchemaNode("boolean"),
+      any: () => createSchemaNode("any"),
+      enum: (values: readonly unknown[]) => createSchemaNode("enum", [...values]),
+      union: (values: readonly unknown[]) => createSchemaNode("union", [...values]),
+      array: (inner: unknown) => createSchemaNode("array", undefined, inner),
+    },
+  },
+);