@aefree/pi-plastic 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows semantic versioning for public package releases.
 
+## Unreleased
+
+## [0.5.5] - 2026-08-14
+
+### Changed
+
+- Made `plastic_status(machineReadable=true, format="json")` return compact parsed pending-item records, aggregate counts, and bounded-item metadata, with package-owned field separation and revision IDs. It returns at most 100 items by default (configurable up to 500); raw, unbounded Plastic output is omitted by default and available with `includeRaw=true` only for diagnostics.
+
+## [0.5.4] - 2026-08-13
+
+### Fixed
+
+- Recognize both `smartbranch` and `br` branch forms in Plastic workspace selectors, including quoted values produced by different checkout workflows.
+- Use a valid local selector as the footer's authoritative branch source instead of launching an unnecessary `cm status` process; malformed or missing branch selectors retain the bounded CLI fallback.
+
 ## [0.5.3] - 2026-08-09
 
 ### Changed

package/README.md

@@ -4,7 +4,7 @@ Pi tools, footer status, and skill guidance for Plastic SCM / Unity Version Cont
 
 ## Plastic branch footer status
 
-When Pi starts inside a Plastic workspace, this package adds a themed `Plastic <branch>` status to Pi's built-in footer. It discovers the nearest enclosing `.plastic/plastic.workspace`, reads the local selector as a fast credential-free fallback, and confirms the branch with a bounded `cm status` call. Selector changes and successful same-workspace `plastic_*` tools refresh the status; sibling workspaces are ignored.
+When Pi starts inside a Plastic workspace, this package adds a themed `Plastic <branch>` status to Pi's built-in footer. It discovers the nearest enclosing `.plastic/plastic.workspace` and reads either the selector's `smartbranch` or `br` form as the credential-free branch source. A bounded `cm status` call is used only when the selector has no valid branch. Selector changes and successful same-workspace `plastic_*` tools refresh the status; sibling workspaces are ignored.
 
 The extension owns only the `plastic-branch` status key. It does not replace Pi's footer or suppress Pi's Git branch display, so Git and Plastic information can appear together in nested workspaces. If the Plastic marker exists but neither the selector nor `cm` yields a branch, the footer shows `Plastic branch unavailable`. Non-Plastic directories show no Plastic status.
 
@@ -74,6 +74,7 @@ The Bash guards run only in Pi processes that actually load this package. A proj
 
 - `plastic_branchCreate` supports an explicit parent branch independent of the loaded workspace branch, defaults relative names to the current branch when no parent is supplied, and rejects top-level paths unless `allowRootBranch=true` is explicit.
 - `plastic_diff` remains a disabled alias by design. Use `plastic_status` for changed-path listing; do not diff as routine post-edit validation or checkin preflight. When change-boundary evidence is needed, use `plastic_diffFile` for one exact file, `plastic_workspaceDiff` with selected paths or explicit `allPending=true`, or `plastic_diffRevisions` for an explicit historical pair. Diff responses use small defaults and caller-controlled `maxChars` bounds. Historical and workspace bytes are copied to ASCII-safe package-owned paths before the backend runs, while normalized headers retain the logical Unicode labels.
+- `plastic_status(machineReadable=true, format="json")` returns parsed `items`, aggregate `summary`, and `itemCount` (`total`, `returned`, `omitted`) rather than requiring agents to parse Plastic rows. It returns at most 100 items by default; set `maxItems` (up to 500) when more are intentional. `includeRaw=true` adds the original unbounded Plastic output for diagnostics, so omit it for normal agent use to conserve context tokens.
 - Preflight is not routine confirmation. Use it for ambiguous or broad mutation scope, moved/deleted path rewriting, compound operations, or explicit preview requests; otherwise rely on exact targets and the tools' runtime guards.
 - `plastic_patch` generates review patches with `cm patch`, including `clean` and `integration` filters for branch review workflows. It does not expose patch apply. Unqualified `br:/...` selectors are qualified only with the current workspace selector's exact repository; otherwise pass `br:/<branch>@<repository>@<server>`.
 - Bash safety rails block `cm diff` and unsafe interactive `cm merge --merge` usage.
@@ -107,13 +108,13 @@ pi install npm:@aefree/pi-plastic
 Install a pinned GitHub release over HTTPS:
 
 ```bash
-pi install git:github.com/aefreedman/pi-plastic@v0.5.3
+pi install git:github.com/aefreedman/pi-plastic@v0.5.4
 ```
 
 Equivalent SSH install:
 
 ```bash
-pi install git:git@github.com/aefreedman/pi-plastic@v0.5.3
+pi install git:git@github.com/aefreedman/pi-plastic@v0.5.4
 ```
 
 To intentionally track the moving default branch instead of a release tag:

package/extensions/plastic-branch-status.ts

@@ -219,7 +219,8 @@ export function createPlasticBranchStatusExtension(overrides: Partial<BranchStat
       if (!active || generation !== ownedGeneration || refreshSequence !== ownedRefresh) return;
 
       const hasSelectorBranch = selectorBranch ? displayBranch(selectorBranch) : false;
-      if (!hasSelectorBranch) displayUnavailable();
+      if (hasSelectorBranch) return;
+      displayUnavailable();
 
       const controller = new AbortController();
       confirmationController = controller;

package/index.ts

@@ -94,6 +94,8 @@ const TOOL_CONFIG: Partial<Record<PlasticExportName, ToolConfig>> = {
       normalizeWorkdirAliases(input);
       assignAlias(input, "includeRevId", ["include_rev_id"]);
       assignAlias(input, "machineReadable", ["machine_readable", "machine"]);
+      assignAlias(input, "maxItems", ["max_items"]);
+      assignAlias(input, "includeRaw", ["include_raw"]);
       return input;
     },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-plastic",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
@@ -34,7 +34,7 @@
     ]
   },
   "scripts": {
-    "test": "npx --yes tsx tests/plastic-tool-validation.ts && npx --yes tsx tests/plastic-checkin-path-resolution.ts && npx --yes tsx tests/plastic-diff-workflow.test.ts && npx --yes tsx tests/plastic-workspace-diff.test.ts && npx --yes tsx tests/plastic-process-lifecycle.test.ts && npx --yes tsx tests/plastic-patch-command.test.ts && npx --yes tsx tests/plastic-extension-registration.test.ts && npx --yes tsx tests/plastic-dynamic-tool-loading.test.ts && npx --yes tsx tests/plastic-tool-rendering.test.ts && npx --yes tsx tests/plastic-branch-query.test.ts && npx --yes tsx tests/plastic-workspace.test.ts && npx --yes tsx tests/plastic-mutation-execution.test.ts && npx --yes tsx tests/file-discovery-filter.test.ts && npx --yes tsx tests/file-discovery-filter-registration.test.ts && npx --yes tsx tests/packed-copy-owner-conflict.test.ts && npx --yes tsx tests/plastic-branch-status.test.ts && npx --yes tsx tests/plastic-constrained-sampling.test.ts && npx --yes tsx tests/bash-cm-diff-guard-validation.ts",
+    "test": "npx --yes tsx tests/plastic-tool-validation.ts && npx --yes tsx tests/plastic-status-machine-readable.test.ts && npx --yes tsx tests/plastic-checkin-path-resolution.ts && npx --yes tsx tests/plastic-diff-workflow.test.ts && npx --yes tsx tests/plastic-workspace-diff.test.ts && npx --yes tsx tests/plastic-process-lifecycle.test.ts && npx --yes tsx tests/plastic-patch-command.test.ts && npx --yes tsx tests/plastic-extension-registration.test.ts && npx --yes tsx tests/plastic-dynamic-tool-loading.test.ts && npx --yes tsx tests/plastic-tool-rendering.test.ts && npx --yes tsx tests/plastic-branch-query.test.ts && npx --yes tsx tests/plastic-workspace.test.ts && npx --yes tsx tests/plastic-mutation-execution.test.ts && npx --yes tsx tests/file-discovery-filter.test.ts && npx --yes tsx tests/file-discovery-filter-registration.test.ts && npx --yes tsx tests/packed-copy-owner-conflict.test.ts && npx --yes tsx tests/plastic-branch-status.test.ts && npx --yes tsx tests/plastic-constrained-sampling.test.ts && npx --yes tsx tests/bash-cm-diff-guard-validation.ts",
     "test:live": "npx --yes tsx tests/plastic-live-smoke.test.ts",
     "test:live:branch-create": "npx --yes tsx tests/plastic-branch-create-live.test.ts",
     "eval:tool-loading": "npx --yes tsx evals/tool-loading/run-eval.ts"

package/src/plastic-core.ts

@@ -326,6 +326,20 @@ type PendingItemSummary = {
     privatePaths: string[];
 };
 
+type MachineReadableStatusItem = {
+    statusCode: string;
+    kind: PendingItemKind;
+    path: string;
+    isDirectory: boolean;
+    revisionId?: string;
+    sourcePath?: string;
+};
+
+type MachineReadableStatusSummary = Omit<PendingItemSummary, "privatePaths">;
+
+const MACHINE_READABLE_STATUS_DEFAULT_MAX_ITEMS = 100;
+const MACHINE_READABLE_STATUS_MAX_ITEMS = 500;
+
 type PrivateAutoAddSelection = {
     candidatePaths: string[];
     blockedPaths: Array<{ path: string; reason: string }>;
@@ -685,6 +699,22 @@ const getMachineReadablePendingItems = async (workdir?: string): Promise<Pending
     return parseMachineReadablePendingItems(output, cwd);
 };
 
+const toMachineReadableStatusItems = (pendingItems: PendingItem[]): MachineReadableStatusItem[] =>
+    pendingItems.map((item) => ({
+        statusCode: item.statusCode,
+        kind: item.kind,
+        path: item.workspacePath,
+        isDirectory: item.isDirectory,
+        ...(item.revisionId ? { revisionId: item.revisionId } : {}),
+        ...(item.sourceWorkspacePath ? { sourcePath: item.sourceWorkspacePath } : {}),
+    }));
+
+const toMachineReadableStatusSummary = (pendingItems: PendingItem[], cwd: string): MachineReadableStatusSummary =>
+{
+    const { privatePaths: _privatePaths, ...summary } = summarizePendingItems(pendingItems, cwd);
+    return summary;
+};
+
 const summarizePendingItems = (pendingItems: PendingItem[], cwd?: string): PendingItemSummary =>
 {
     const summary: PendingItemSummary = {
@@ -2375,7 +2405,9 @@ export const status = tool({
     args: {
         workdir: workdirArg,
         includeRevId: tool.schema.boolean().optional().describe("Include revision IDs in the status output when supported."),
-        machineReadable: tool.schema.boolean().optional().describe("Return machine-readable status output when supported."),
+        machineReadable: tool.schema.boolean().optional().describe("Return parsed, machine-readable pending status records when supported."),
+        maxItems: tool.schema.number().int().min(1).max(MACHINE_READABLE_STATUS_MAX_ITEMS).optional().describe(`Maximum parsed items in machine-readable JSON (default ${MACHINE_READABLE_STATUS_DEFAULT_MAX_ITEMS}, maximum ${MACHINE_READABLE_STATUS_MAX_ITEMS}).`),
+        includeRaw: tool.schema.boolean().optional().describe("Include unbounded raw machine-readable Plastic output in JSON diagnostics. Applies only when machineReadable=true."),
         short: tool.schema.boolean().optional().describe("Use short status output."),
         format: outputFormatArg,
     },
@@ -2396,15 +2428,32 @@ export const status = tool({
 
         if (args.machineReadable)
         {
-            cmdArgs.push("--machinereadable");
+            // Package-owned separators make paths with whitespace unambiguous, and
+            // revision IDs let agents safely identify the base of moved/deleted items.
+            if (!cmdArgs.includes("--includeRevId"))
+            {
+                cmdArgs.push("--includeRevId");
+            }
+            cmdArgs.push("--machinereadable", `--fieldseparator=${STATUS_FIELD_SEPARATOR}`);
             const machineOutput = await runCmRaw(cmdArgs, args.workdir);
+            const cwd = args.workdir ?? process.cwd();
+            const pendingItems = parseMachineReadablePendingItems(machineOutput, cwd);
+            const maxItems = args.maxItems ?? MACHINE_READABLE_STATUS_DEFAULT_MAX_ITEMS;
+            const returnedItems = pendingItems.slice(0, maxItems);
             return toStructuredResult(
                 "status",
                 format,
                 machineOutput,
                 {
-                    rawOutput: machineOutput,
                     machineReadable: true,
+                    items: toMachineReadableStatusItems(returnedItems),
+                    itemCount: {
+                        total: pendingItems.length,
+                        returned: returnedItems.length,
+                        omitted: pendingItems.length - returnedItems.length,
+                    },
+                    summary: toMachineReadableStatusSummary(pendingItems, cwd),
+                    ...(args.includeRaw ? { rawOutput: machineOutput } : {}),
                 },
                 args.workdir,
             );

package/src/plastic-workspace.ts

@@ -78,7 +78,8 @@ const parseSelectorValue = (line: string, key: string): string | undefined => {
 /** Parse the local selector without treating it as proof that a workspace exists. */
 export function parsePlasticSelector(content: string): ParseOutcome<PlasticSelector> {
   let repository: string | undefined;
-  let branch: string | undefined;
+  let smartBranch: string | undefined;
+  let explicitBranch: string | undefined;
   let sawBranchKey = false;
 
   for (const line of content.split(/\r?\n/)) {
@@ -86,13 +87,18 @@ export function parsePlasticSelector(content: string): ParseOutcome<PlasticSelec
     if (/^\s*repository(?:\s|$)/i.test(line)) repository = parseSelectorValue(line, "repository");
     if (/^\s*smartbranch(?:\s|$)/i.test(line)) {
       sawBranchKey = true;
-      branch = parseSelectorValue(line, "smartbranch");
+      smartBranch = parseSelectorValue(line, "smartbranch");
+    }
+    if (/^\s*br(?:\s|$)/i.test(line)) {
+      sawBranchKey = true;
+      explicitBranch = parseSelectorValue(line, "br");
     }
   }
 
   if (!sawBranchKey) return { kind: "not_found" };
+  const branch = smartBranch ?? explicitBranch;
   if (!branch || /[\u0000-\u001f\u007f]/.test(branch)) {
-    return { kind: "malformed", reason: "Selector smartbranch is blank or contains control characters." };
+    return { kind: "malformed", reason: "Selector branch is blank or contains control characters." };
   }
 
   return {