@aefree/pi-plastic 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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

package/README.md

@@ -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.

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.4",
+  "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,
             );