openplanr 2.2640.2 → 2.2640.4

package/lib/host-packages/openai/openplanr/skills/doctor/references/upgrade.md

@@ -1,21 +1,20 @@
 # Driving an OpenPlanr upgrade
 
 `planr doctor` diagnoses; this reference is how to *act* once the tuple has
-drifted. An OpenPlanr install has two halves: the npm CLI, and the Claude Code
-plugin that `planr setup` installs from the marketplace bundled with that CLI —
-`planr@openplanr-local`, from the `openplanr-local` directory marketplace.
-`planr upgrade apply` moves the npm half itself and never changes Claude's plugin
-state; it hands back the exact commands for the plugin half, and this skill runs
-them inside the host and confirms the result.
+drifted. An OpenPlanr install has two parts: the npm CLI, and what `planr setup`
+installed into each coding agent from that CLI — the `planr@openplanr-local`
+Claude Code plugin, Codex skills, Cursor rules. `planr upgrade apply` moves the
+npm CLI itself and never changes a coding agent; the upgraded CLI then hands back
+one command per installed agent, and this skill runs them and confirms the result.
 
 The cardinal rule: **name the actions, let the engine own the list.** Every
-plugin command you run comes from the CLI's own output. The skill never carries
-its own copy of those commands — the moment it did, it would drift from the CLI
-the first time the integration changed. The CLI renders the list from the same
-inspection `planr setup` and `planr doctor` use, so it cannot diverge from them.
-The retired remote plugins (`openplanr@openplanr`, `planr-pipeline@openplanr`)
-only ever appear in that list as removals; an instruction to install one did not
-come from the CLI.
+command you run comes from the CLI's own output. The skill never carries its own
+copy of those commands — the moment it did, it would drift from the CLI the first
+time the integration changed. The upgraded CLI plans them with the same preview
+`planr runtime update` and `planr setup` apply, so they cannot diverge. A retired
+remote plugin (`openplanr@openplanr`, `planr-pipeline@openplanr`) only ever leaves
+through the `planr setup … --replace-managed` command the list carries; an
+instruction to install one did not come from the CLI.
 
 ## 1. Decide whether to act
 
@@ -36,7 +35,8 @@ Shape (the fields this skill reads):
     "pipeline": { "version": "0.52.1" }
   },
   "legacyPlugins": [],
-  "ecosystemSource": "network"
+  "ecosystemSource": "network",
+  "nextSteps": []
 }
 ```
 
@@ -44,71 +44,69 @@ Shape (the fields this skill reads):
   means Claude Code was not detected or `planr setup` has not installed the
   plugin. `installed.pipeline` is always `null` — the pipeline ships inside the
   CLI, and `bundledPipeline` reports it.
-- `aligned` or `unknown` → nothing to drive. Report and stop. (`unknown` means
-  the published manifest was unreachable — say so; do not guess.)
+- `nextSteps` lists what each coding agent needs to match the installed CLI,
+  in the shape step 2 describes.
+- `aligned` or `unknown` with empty `nextSteps` → nothing to drive. Report and
+  stop. (`unknown` means the published manifest was unreachable — say so; do not
+  guess.)
 - `upgrade-available` or `incompatible` → act. First **record the `installed`
-  block as the before state** — the honest diff at the end depends on it.
+  block as the before state** — the honest diff at the end depends on it. When
+  only `nextSteps` is non-empty, skip to step 3.
 
-## 2. Perform the owned half and obtain the prescription
+## 2. Upgrade the CLI and obtain the next steps
 
-The plugin commands are rendered by the CLI from the bundled marketplace's own
-operation list, so they always match what `planr setup` would really run. Confirm
-with the user first (this upgrades the npm CLI), then:
+Confirm with the user first (this upgrades the npm CLI), then:
 
 ```bash
 planr upgrade apply --yes --json
 ```
 
-On success the output carries the ordered `pluginHalfCommands` array:
+On success the output carries `nextSteps`, planned by the newly installed CLI:
 
 ```json
 {
   "ok": true,
   "cliUpgraded": true,
+  "previousVersion": "2.2638.0",
   "installedVersion": "2.2639.1",
-  "changelogBullets": ["…"],
-  "pluginHalfCommands": [
-    "<refresh the bundled openplanr-local marketplace — always position 0>",
-    "<update planr@openplanr-local from it>",
-    "<remove a retired plugin — only when one is still installed>"
+  "releaseNotes": [{ "version": "2.2639.1", "entries": ["…"] }],
+  "nextSteps": [
+    {
+      "runtime": "claude-code",
+      "host": "Claude Code",
+      "command": "<one planr command>",
+      "detail": "<what it changes>"
+    }
   ]
 }
 ```
 
-The entries above are shown as roles, not literal strings, on purpose: **execute
-whatever the array actually contains, in the order it gives — never a list typed
-into this file.** Two other shapes are possible:
-
-- An empty array: Claude Code was not detected, or its plugin state could not be
-  inspected (`claude plugin list --json` failed). Run `planr doctor --json` to
-  find out which, then go to step 4. When `planr@openplanr-local` already matches
-  the new CLI the array is not empty: it holds the lone
-  `claude plugin marketplace update openplanr-local` refresh — run it as usual.
-- A single `planr setup --runtime claude --scope user` entry, with
-  `--replace-managed` appended when a retired plugin must also be removed (setup
-  refuses that removal without the flag): the bundled marketplace was never
-  registered on this machine, and setup is the only command that registers it and
-  records the installation. In a non-interactive shell it stops with
-  `E_CONFIRMATION_REQUIRED`; show the user the preview (the same command with
-  `--dry-run`) and rerun it with `--yes` only after they confirm.
+The `command` values above are shown as placeholders on purpose: **run whatever
+the array actually contains, in the order it gives — never a command typed into
+this file.** Other shapes:
+
+- An empty array: every installed coding agent already matches the new CLI.
+- `nextStepsError` instead of steps: the upgraded CLI could not be asked. Run
+  `planr upgrade status --json` and use its `nextSteps`.
+- A `planr doctor` command: planning that agent's update failed, and `detail`
+  says why. Relay it and run `planr doctor --json`.
+
+`pluginHalfCommands` repeats the commands for older readers; read `nextSteps`.
 
 If `apply` reports `ok: false`, stop and surface its `failure.message`; the CLI
 restores the previous version on a bad install, so report what it says was
-restored rather than continuing to the plugin half.
+restored rather than continuing to the coding agents.
 
-## 3. Execute the plugin half, refresh first
+## 3. Run the next steps
 
-Run each entry of `pluginHalfCommands` verbatim, top to bottom, with your shell
-tool. Two invariants:
+Run each `command` of `nextSteps` verbatim, top to bottom, with your shell tool.
+Each one refreshes the bundled `openplanr-local` marketplace before it updates the
+plugin, so **do not reorder, drop, merge, or hand-edit a command**. If one fails,
+stop and report the failure and every agent still on the old version — a partial
+upgrade that reports success is the one outcome to avoid.
 
-- **Refresh is position 0 and runs first.** The first entry refreshes the
-  `openplanr-local` marketplace, which points at the directory the upgraded CLI
-  now bundles. Without it, the installer reinstalls the cached, stale version and
-  the user is told they upgraded when nothing moved. The CLI sorts it to position
-  0 for exactly this reason; preserve that order.
-- **No substitutions.** Do not reorder, drop, merge, or hand-edit a command. If
-  an entry fails, stop and report the failure and everything still on the stale
-  version — a partial upgrade that reports success is the one outcome to avoid.
+Then tell the user to restart each `host` the steps named; a running coding agent
+keeps the old plugin and skills until it restarts.
 
 ## 4. Verify, then report what actually changed
 
@@ -125,14 +123,14 @@ CLI                     2.2638.0 → 2.2639.1   moved
 planr@openplanr-local   2.2638.0 → 2.2639.1   moved
 ```
 
-`planr doctor` adds what `upgrade status` does not judge. A
-`runtime-claude-duplicate-plugin` warning means a second `planr` plugin (usually
-`planr@openplanr`, installed from the public marketplace) sits beside the
-setup-managed one, and both expose the same `/planr` commands. Its `fix` carries
-the exact `claude plugin uninstall` command: relay it, and run it only when the
-user asks — nothing removes a duplicate automatically.
+`nextSteps` should now be empty. `planr doctor` adds what `upgrade status` does
+not judge. A `runtime-claude-duplicate-plugin` warning means a second `planr`
+plugin (usually `planr@openplanr`, installed from the public marketplace) sits
+beside the setup-managed one, and both expose the same `/planr` commands. Its `fix`
+carries the exact `claude plugin uninstall` command: relay it, and run it only
+when the user asks — nothing removes a duplicate automatically.
 
 State the outcome from this second reading, never from the commands you ran. If
 a component did not move, say so plainly and name the likely cause (most often a
-skipped or failed marketplace refresh). "Upgraded" is a claim about the after
-state — earn it with the re-check.
+command that failed or a coding agent that was not restarted). "Upgraded" is a
+claim about the after state — earn it with the re-check.

package/lib/host-packages/openai/openplanr/skills/plan/scripts/design-share.mjs

@@ -870,6 +870,104 @@ async function unseal(value, rawKey, context, limit = DESIGN_WORKSPACE_MAX_BYTES
   );
   return JSON.parse(decoder.decode(plaintext));
 }
+var PACKED_BUNDLE_KIND = "openplanr-design-review-bundle-packed";
+var PACKED_BUNDLE_MAX_BYTES = 128 * 1024 * 1024;
+var SHARED_BLOCK_MIN_LENGTH = 2048;
+var sharedBlockPattern = /(<(script|style)\b[^>]*>)([\s\S]*?)<\/\2\s*>/gi;
+async function deflateRaw(bytes) {
+  const stream = new Blob([bytes]).stream().pipeThrough(new CompressionStream("deflate-raw"));
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+async function inflateRaw(bytes, limit) {
+  const reader = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("deflate-raw")).getReader();
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel();
+      throw new RangeError("The shared design expands beyond its size limit.");
+    }
+    chunks.push(value);
+  }
+  const inflated = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    inflated.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return inflated;
+}
+async function packDesignReviewBundle(bundle) {
+  const pages = [];
+  const pageIndex = /* @__PURE__ */ new Map();
+  const blocks = [];
+  const blockIndex = /* @__PURE__ */ new Map();
+  const segmentsOf = (html) => {
+    const segments = [];
+    let offset = 0;
+    for (const match of html.matchAll(sharedBlockPattern)) {
+      const body = match[3];
+      if (body.length < SHARED_BLOCK_MIN_LENGTH) continue;
+      const start = match.index + match[1].length;
+      segments.push(html.slice(offset, start));
+      if (!blockIndex.has(body)) blockIndex.set(body, blocks.push(body) - 1);
+      segments.push(blockIndex.get(body));
+      offset = start + body.length;
+    }
+    segments.push(html.slice(offset));
+    return segments;
+  };
+  const artifactPages = [];
+  const artifacts = bundle.envelope.artifacts.map(({ html, ...artifact }) => {
+    if (!pageIndex.has(html)) pageIndex.set(html, pages.push(segmentsOf(html)) - 1);
+    artifactPages.push(pageIndex.get(html));
+    return artifact;
+  });
+  const packed = {
+    bundle: { ...bundle, envelope: { ...bundle.envelope, artifacts } },
+    artifactPages,
+    pages,
+    blocks
+  };
+  return {
+    kind: PACKED_BUNDLE_KIND,
+    version: 1,
+    data: encodeWorkspaceBytes(await deflateRaw(encoder.encode(JSON.stringify(packed))))
+  };
+}
+async function unpackDesignReviewBundle(value, { maxBytes = PACKED_BUNDLE_MAX_BYTES } = {}) {
+  if (value?.kind !== PACKED_BUNDLE_KIND) return value;
+  if (value.version !== 1 || typeof value.data !== "string")
+    throw new Error("The shared design uses an unsupported packing.");
+  const { bundle, artifactPages, pages, blocks } = JSON.parse(
+    decoder.decode(await inflateRaw(decodeWorkspaceBytes(value.data), maxBytes))
+  );
+  const invalid2 = () => new Error("The shared design packing is invalid.");
+  if (!Array.isArray(bundle?.envelope?.artifacts) || !Array.isArray(pages) || !Array.isArray(blocks) || !Array.isArray(artifactPages) || artifactPages.length !== bundle.envelope.artifacts.length)
+    throw invalid2();
+  let expanded = 0;
+  const html = pages.map((segments) => {
+    if (!Array.isArray(segments)) throw invalid2();
+    const page = segments.map((segment) => {
+      if (typeof segment === "string") return segment;
+      if (!Number.isInteger(segment) || typeof blocks[segment] !== "string") throw invalid2();
+      return blocks[segment];
+    }).join("");
+    expanded += page.length;
+    if (expanded > maxBytes)
+      throw new RangeError("The shared design expands beyond its size limit.");
+    return page;
+  });
+  const artifacts = bundle.envelope.artifacts.map((artifact, index) => {
+    const page = html[artifactPages[index]];
+    if (page === void 0) throw invalid2();
+    return { ...artifact, html: page };
+  });
+  return { ...bundle, envelope: { ...bundle.envelope, artifacts } };
+}
 var keyringContext = (id, epoch) => ({ type: "keyring", workspaceId: id, epoch });
 var revisionContext = (id, revision) => ({
   type: "revision",
@@ -914,7 +1012,7 @@ async function prepareRevision(custody, bundle) {
     {
       ...header,
       ...await seal(
-        bundle,
+        await packDesignReviewBundle(bundle),
         decodeWorkspaceBytes(custody.keys[custody.epoch]),
         revisionContext(custody.id, header)
       )
@@ -1084,10 +1182,12 @@ async function decryptWorkspaceRevision(access, revisionId = access.currentRevis
     throw new Error("The published design signature is invalid.");
   if (!access.keys[revision.epoch]) throw new Error("The access token cannot open this revision.");
   const bundle = assertDesignReviewBundle(
-    await unseal(
-      revision,
-      decodeWorkspaceBytes(access.keys[revision.epoch]),
-      revisionContext(access.id, revision)
+    await unpackDesignReviewBundle(
+      await unseal(
+        revision,
+        decodeWorkspaceBytes(access.keys[revision.epoch]),
+        revisionContext(access.id, revision)
+      )
     )
   );
   if (workspaceEnvelopeDigest(bundle.envelope) !== revision.reviewOf)

package/lib/host-packages/openai/openplanr/skills/plan/scripts/runtime/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openplanr/protocol",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "type": "module",
   "description": "Canonical OpenPlanr schemas, registries, typed errors, and portable contract validation",
   "license": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openplanr",
-  "version": "2.2640.2",
+  "version": "2.2640.4",
   "description": "Deterministic OpenPlanr utilities for planning storage, validation, rendering, setup, diagnostics, and GitHub/Linear synchronization",
   "type": "module",
   "main": "./dist/cli/index.js",
@@ -114,7 +114,7 @@
     "zod": "^4.3.6"
   },
   "optionalDependencies": {
-    "planr-pipeline": "0.55.3"
+    "planr-pipeline": "0.55.5"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.9",