@piagent/platform 1.4.0 → 1.5.1

package/scripts/uninstall-global.sh

@@ -80,6 +80,46 @@ run_cmd() {
   fi
 }
 
+# The helper can live under a non-default npm prefix: install falls back to a
+# user-writable root when the configured one is not writable, and --npm-prefix
+# picks one deliberately. A bare `npm uninstall -g` resolves against the
+# configured prefix instead, so it removes nothing and still reports success.
+# Derive the prefix from where this script actually runs, the same way
+# update-global.mjs does, and only add --prefix when it differs.
+installed_helper_prefix() {
+  local root="$ROOT"
+  [[ "$(basename "$root")" == "platform" ]] || return 0
+  local scope_root node_modules_root parent
+  scope_root="$(dirname "$root")"
+  [[ "$(basename "$scope_root")" == "@piagent" ]] || return 0
+  node_modules_root="$(dirname "$scope_root")"
+  [[ "$(basename "$node_modules_root")" == "node_modules" ]] || return 0
+  parent="$(dirname "$node_modules_root")"
+  # An npx run lives in a prunable cache that owns no bin on anyone's PATH;
+  # uninstalling from there would claim to remove an install nobody has.
+  case "$parent" in
+    */_npx/*|*/_npx) return 0 ;;
+  esac
+  if [[ "$(basename "$parent")" == "lib" ]]; then
+    dirname "$parent"
+  else
+    printf '%s' "$parent"
+  fi
+}
+
+# The prefix npm has to be pointed at, or empty when the helper already lives
+# under the configured one and the plain command is correct. Returns a single
+# value rather than an argument list: macOS still ships bash 3.2, where
+# expanding an empty array under `set -u` aborts the script.
+npm_prefix_override() {
+  local helper_prefix configured
+  helper_prefix="$(installed_helper_prefix)"
+  [[ -n "$helper_prefix" ]] || return 0
+  configured="$(npm prefix -g 2>/dev/null || true)"
+  [[ "$helper_prefix" != "$configured" ]] || return 0
+  printf '%s' "$helper_prefix"
+}
+
 # Reads the package sources Pi has registered, so removal targets what is
 # actually installed rather than what this version happens to install today. An
 # older release registered a different source shape, and it still has to come
@@ -174,7 +214,13 @@ if [[ "$WITH_HOST" == true ]]; then
   echo
   if command -v npm >/dev/null 2>&1; then
     echo "Uninstalling Pi host:"
-    run_cmd npm uninstall -g "$PI_HOST_PACKAGE"
+    HOST_PREFIX="$(npm_prefix_override)"
+    if [[ -n "$HOST_PREFIX" ]]; then
+      echo "  (prefix $HOST_PREFIX, where this helper is installed)"
+      run_cmd npm uninstall -g --prefix "$HOST_PREFIX" "$PI_HOST_PACKAGE"
+    else
+      run_cmd npm uninstall -g "$PI_HOST_PACKAGE"
+    fi
   else
     echo "WARN: npm is not on PATH; cannot uninstall $PI_HOST_PACKAGE." >&2
   fi
@@ -231,7 +277,12 @@ echo
 if [[ "$APPLY" == true ]]; then
   echo "Uninstall complete."
   echo "The npm-global helper is separate and stays until you remove it:"
-  echo "  npm uninstall -g $PLATFORM_PACKAGE"
+  HELPER_PREFIX="$(npm_prefix_override)"
+  if [[ -n "$HELPER_PREFIX" ]]; then
+    echo "  npm uninstall -g --prefix $HELPER_PREFIX $PLATFORM_PACKAGE"
+  else
+    echo "  npm uninstall -g $PLATFORM_PACKAGE"
+  fi
 else
   echo "Dry run only. Nothing was removed. Re-run with --apply to perform it."
 fi

package/scripts/update-global.mjs

@@ -213,8 +213,21 @@ function binForPrefix(prefix) {
   return process.platform === "win32" ? prefix : path.join(prefix, "bin");
 }
 
+// The npx cache is a `node_modules` tree like any other, so the documented
+// bootstrap -- `npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update`
+// -- ran the helper from `~/.npm/_npx/<hash>/node_modules/@piagent/platform` and
+// this function happily reported that hash directory as the prefix to install
+// into. Host and helper then landed in a cache npm is free to prune, with a `bin`
+// that is on nobody's PATH: the command reported success and the machine had
+// nothing installed. A cache is never an install target, so it is refused here
+// and the caller falls back to a real global prefix.
+function isNpxCacheRoot(root) {
+  return root.split(path.sep).some((segment) => segment === "_npx" || segment === "_cacache");
+}
+
 function npmPrefixForInstalledHelper(root) {
   if (path.basename(root) !== "platform") return undefined;
+  if (isNpxCacheRoot(root)) return undefined;
   const scopeRoot = path.dirname(root);
   if (path.basename(scopeRoot) !== "@piagent") return undefined;
   const nodeModulesRoot = path.dirname(scopeRoot);
@@ -444,10 +457,29 @@ function main() {
     console.log(`  npm:     using explicit global prefix ${npmTarget.prefix}`);
   }
 
+  // The host version above was read before this prepend, so it described whatever
+  // `pi` the caller's PATH happened to resolve. Once the prefix moves -- a default
+  // global root that is not writable, an explicit `--npm-prefix`, or a helper
+  // already installed elsewhere -- every step below uses a different `pi`, and
+  // "(already current)" could be describing a binary this run never touches. The
+  // decision belongs to the `pi` that will actually be used, so it is taken again
+  // here rather than trusted from before the move.
+  let effectiveHost = currentHost;
+  let effectiveHostNeedsChange = hostNeedsChange;
+  if (npmTarget.bin) {
+    const activeHost = installedHostVersion();
+    if (activeHost !== currentHost) {
+      effectiveHost = activeHost;
+      effectiveHostNeedsChange = options.host && (options.force || activeHost !== targetHost);
+      console.log(`  host:    the active prefix resolves pi ${activeHost ?? "not installed"}, not ${currentHost ?? "not installed"};`
+        + ` using ${effectiveHost ?? "not installed"} -> ${targetHost}${effectiveHostNeedsChange ? "" : " (already current)"}`);
+    }
+  }
+
   // Host first: piagent-install refuses to run against a host that does not match
   // the version its package.json pins, so a helper installed ahead of the host
   // would fail on its very next step.
-  if (hostNeedsChange) {
+  if (effectiveHostNeedsChange) {
     const args = npmInstallArgs(`${HOST_PACKAGE}@${targetHost}`, npmTarget);
     describeStep(options.dryRun, "npm", args);
     if (!options.dryRun && !run("npm", args).ok) fail(`could not install ${HOST_PACKAGE}@${targetHost}`);

package/scripts/verify-local.sh

@@ -173,6 +173,7 @@ required_files=(
   "$ROOT/scripts/build-docs-site.mjs"
   "$ROOT/scripts/check-architecture.mjs"
   "$ROOT/scripts/check-doc-languages.mjs"
+  "$ROOT/scripts/verify-translation-pairing.mjs"
   "$ROOT/scripts/check-third-party-neutrality.mjs"
   "$ROOT/governance/piagent-webui/wui5-18-acceptance-matrix.v1.json"
   "$ROOT/tests/piagent-webui-wui5-18-gate.test.mjs"
@@ -205,6 +206,7 @@ required_files=(
   "$ROOT/schemas/piagent-webui/queue-v1.schema.json"
   "$ROOT/schemas/piagent-webui/model-catalog-v1.schema.json"
   "$ROOT/schemas/piagent-webui/attachment-v1.schema.json"
+  "$ROOT/schemas/piagent-webui/document-workspace-v1.schema.json"
   "$ROOT/schemas/piagent-webui/control-command-v1.schema.json"
   "$ROOT/schemas/piagent-webui/approval-v1.schema.json"
   "$ROOT/schemas/piagent-webui/capabilities-v1.schema.json"
@@ -231,6 +233,7 @@ required_files=(
   "$ROOT/packages/piagent-webui/contracts/generated/queue-v1.ts"
   "$ROOT/packages/piagent-webui/contracts/generated/model-catalog-v1.ts"
   "$ROOT/packages/piagent-webui/contracts/generated/attachment-v1.ts"
+  "$ROOT/packages/piagent-webui/contracts/generated/document-workspace-v1.ts"
   "$ROOT/packages/piagent-webui/contracts/generated/session-catalog-v1.ts"
   "$ROOT/packages/piagent-webui/contracts/generated/session-command-v1.ts"
   "$ROOT/packages/piagent-webui/contracts/generated/gateway-capabilities-v1.ts"
@@ -248,6 +251,9 @@ required_files=(
   "$ROOT/packages/piagent-webui/client/src/evidence-view-model.ts"
   "$ROOT/packages/piagent-webui/client/src/EvidencePanels.tsx"
   "$ROOT/packages/piagent-webui/client/src/ChatPanel.tsx"
+  "$ROOT/packages/piagent-webui/client/src/MarkdownMessage.tsx"
+  "$ROOT/packages/piagent-webui/client/src/DocumentWorkspace.tsx"
+  "$ROOT/packages/piagent-webui/client/src/attachment-intake.ts"
   "$ROOT/packages/piagent-webui/client/src/chat-view-model.ts"
   "$ROOT/packages/piagent-webui/client/src/chat-command.ts"
   "$ROOT/packages/piagent-webui/client/src/review-command.ts"
@@ -291,6 +297,8 @@ required_files=(
   "$ROOT/packages/piagent-webui/gateway/mcp-auth-broker.ts"
   "$ROOT/tests/piagent-webui-mcp-auth.test.mjs"
   "$ROOT/packages/piagent-webui/gateway/session-catalog.ts"
+  "$ROOT/packages/piagent-webui/gateway/ai-capability-inspection.ts"
+  "$ROOT/packages/piagent-webui/gateway/session-attachment-registry.ts"
   "$ROOT/packages/piagent-webui/gateway/session-command-controller.ts"
   "$ROOT/packages/piagent-webui/gateway/session-command-store.ts"
   "$ROOT/packages/piagent-webui/gateway/session-lease-store.ts"
@@ -304,6 +312,11 @@ required_files=(
   "$ROOT/packages/piagent-webui/extension/source-open-controller.ts"
   "$ROOT/packages/piagent-webui/extension/vscode-handoff.ts"
   "$ROOT/packages/piagent-core/runtime/inspection/review-state-contract.ts"
+  "$ROOT/packages/piagent-core/runtime/inspection/document-workspace-projection.ts"
+  "$ROOT/packages/piagent-core/runtime/inspection/session-identity.ts"
+  "$ROOT/packages/piagent-core/runtime/input/attachment-reservation.ts"
+  "$ROOT/packages/piagent-core/runtime/input/attachment-document-command.ts"
+  "$ROOT/packages/piagent-core/runtime/input/attachment-store.ts"
   "$ROOT/packages/piagent-core/runtime/inspection/mcp-control.ts"
   "$ROOT/packages/piagent-core/runtime/inspection/review-state-projection.ts"
   "$ROOT/packages/piagent-core/runtime/inspection/review-state-store.ts"
@@ -346,7 +359,6 @@ required_files=(
   "$ROOT/packages/piagent-webui/extension/held-message-queue.ts"
   "$ROOT/packages/piagent-webui/extension/session-options-controller.ts"
   "$ROOT/packages/piagent-webui/extension/session-stream-adapter.ts"
-  "$ROOT/packages/piagent-webui/extension/attachment-store.ts"
   "$ROOT/packages/piagent-webui/extension/lifecycle-controller.ts"
   "$ROOT/packages/piagent-webui/extension/lifecycle-event-adapter.ts"
   "$ROOT/packages/piagent-core/runtime/inspection/approval-broker.ts"
@@ -359,6 +371,8 @@ required_files=(
   "$ROOT/tests/piagent-webui-held-message-queue.test.mjs"
   "$ROOT/tests/piagent-webui-session-options.test.mjs"
   "$ROOT/tests/piagent-webui-attachment-store.test.mjs"
+  "$ROOT/tests/piagent-webui-document-workspace.test.mjs"
+  "$ROOT/tests/helpers/piagent-docx-fixture.mjs"
   "$ROOT/tests/piagent-webui-approval-broker.test.mjs"
   "$ROOT/tests/piagent-webui-lifecycle-control.test.mjs"
   "$ROOT/tests/piagent-webui-lifecycle-client.test.mjs"
@@ -570,6 +584,8 @@ const jsonFiles = [
   "schemas/piagent-webui/transcript-v1.schema.json",
   "schemas/piagent-webui/queue-v1.schema.json",
   "schemas/piagent-webui/model-catalog-v1.schema.json",
+  "schemas/piagent-webui/attachment-v1.schema.json",
+  "schemas/piagent-webui/document-workspace-v1.schema.json",
   "schemas/piagent-webui/control-command-v1.schema.json",
   "schemas/piagent-webui/approval-v1.schema.json",
   "schemas/piagent-webui/capabilities-v1.schema.json",
@@ -914,6 +930,9 @@ node --check "$ROOT/scripts/build-docs-site.mjs" >/dev/null
 node --check "$ROOT/scripts/preview-docs-site.mjs" >/dev/null
 node "$ROOT/scripts/check-architecture.mjs" >/dev/null
 node "$ROOT/scripts/check-doc-languages.mjs" >/dev/null
+# check-doc-languages proves the peer exists. This proves neither side moved
+# without the other, which is the way a translation actually goes stale.
+node "$ROOT/scripts/verify-translation-pairing.mjs" >/dev/null
 node "$ROOT/scripts/check-third-party-neutrality.mjs" >/dev/null
 run_quietly "npm run build --workspace @piagent/webui" npm run build --workspace @piagent/webui
 run_quietly "npm test" npm test

package/scripts/verify-translation-pairing.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Fails when one side of a bilingual pair has moved and the other has not.
+//
+// The existing language gate proves the Vietnamese peer exists. Existing is not
+// the same as saying the same thing: editing docs/en/architecture.md and
+// forgetting docs/vi/architecture.md passes every check in this repository,
+// and the reader of the stale side has no way to know.
+//
+// So each pair carries the content digest of both sides as of the last time
+// somebody confirmed them consistent. A digest that no longer matches means the
+// record is stale, and the fix is to bring the other side along and re-record.
+//
+// What this cannot do is read the two documents and decide they agree. It is a
+// record that a human looked, nothing more -- which is worth exactly as much as
+// the honesty of whoever runs --write.
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function contentDigest(text) {
+  // Newline-normalised so a checkout on another platform does not read as drift.
+  return createHash("sha256").update(text.replace(/\r\n/g, "\n"), "utf8").digest("hex").slice(0, 40);
+}
+
+export function digestForFile(root, relative) {
+  const file = path.join(root, relative);
+  if (!fs.existsSync(file)) return null;
+  return contentDigest(fs.readFileSync(file, "utf8"));
+}
+
+/**
+ * @param {{root?: string, manifest?: object}} options
+ * @returns {{ok: boolean, checked: number, unrecorded: string[], drifted: object[], stale: object[], missing: string[]}}
+ */
+export function inspectPairing({ root = repositoryRoot, manifest } = {}) {
+  const languages = manifest
+    ?? JSON.parse(fs.readFileSync(path.join(root, "docs", "languages.json"), "utf8"));
+  const result = { ok: true, checked: 0, unrecorded: [], drifted: [], stale: [], missing: [] };
+
+  for (const pair of languages.pairs ?? []) {
+    const current = { en: digestForFile(root, pair.en), vi: digestForFile(root, pair.vi) };
+    for (const side of ["en", "vi"]) {
+      if (current[side] === null) result.missing.push(`${pair.topic}: ${pair[side]} does not exist`);
+    }
+    if (current.en === null || current.vi === null) { result.ok = false; continue; }
+
+    result.checked += 1;
+    const recorded = pair.consistentAt;
+    if (!recorded) { result.unrecorded.push(pair.topic); result.ok = false; continue; }
+
+    const movedSides = ["en", "vi"].filter((side) => recorded[side] !== current[side]);
+    if (movedSides.length === 0) continue;
+    result.ok = false;
+    // One side moving alone is the failure this exists for: the other side is
+    // now describing something that changed. Both moving is likely a paired
+    // edit, but nothing here can prove it, so it still needs re-recording.
+    const entry = { topic: pair.topic, moved: movedSides, en: pair.en, vi: pair.vi };
+    if (movedSides.length === 1) result.drifted.push(entry);
+    else result.stale.push(entry);
+  }
+  return result;
+}
+
+function record(root) {
+  const file = path.join(root, "docs", "languages.json");
+  const languages = JSON.parse(fs.readFileSync(file, "utf8"));
+  for (const pair of languages.pairs ?? []) {
+    const en = digestForFile(root, pair.en);
+    const vi = digestForFile(root, pair.vi);
+    if (en === null || vi === null) continue;
+    pair.consistentAt = { en, vi };
+  }
+  fs.writeFileSync(file, `${JSON.stringify(languages, null, 2)}\n`);
+  return languages.pairs.length;
+}
+
+const invokedDirectly = process.argv[1]
+  && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+
+if (invokedDirectly) {
+  const write = process.argv.includes("--write");
+  if (process.argv.includes("-h") || process.argv.includes("--help")) {
+    console.log(`Usage:
+  node scripts/verify-translation-pairing.mjs [--write]
+
+Checks that neither side of a bilingual documentation pair has moved since the
+two were last confirmed consistent. --write re-records the current state, which
+is a claim that you brought both sides into line.`);
+    process.exit(0);
+  }
+  if (write) {
+    console.log(`Recorded ${record(repositoryRoot)} pairs as consistent.`);
+    process.exit(0);
+  }
+
+  const result = inspectPairing();
+  if (result.ok) {
+    console.log(`PASS: ${result.checked} bilingual pairs match their recorded state`);
+    process.exit(0);
+  }
+  for (const line of result.missing) console.error(`FAIL: ${line}`);
+  for (const topic of result.unrecorded) {
+    console.error(`FAIL: ${topic} has no recorded consistent state.`);
+  }
+  for (const entry of result.drifted) {
+    const moved = entry.moved[0];
+    const other = moved === "en" ? "vi" : "en";
+    console.error(`FAIL: ${entry.topic}: ${entry[moved]} changed and ${entry[other]} did not.`);
+    console.error(`      Bring ${entry[other]} along, then re-record.`);
+  }
+  for (const entry of result.stale) {
+    console.error(`FAIL: ${entry.topic}: both sides changed, so the record no longer says anything.`);
+    console.error(`      Confirm they still agree, then re-record.`);
+  }
+  console.error("\nRe-record with: node scripts/verify-translation-pairing.mjs --write");
+  process.exit(1);
+}