@plur-ai/migrate 0.16.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 PLUR (plur.ai)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,60 @@
+# @plur-ai/migrate
+
+Find PLUR calls left un-awaited by the 0.16 async migration.
+
+```bash
+npx @plur-ai/migrate            # report (default — changes nothing)
+npx @plur-ai/migrate --write    # apply the unambiguous fixes
+```
+
+## Why you need this
+
+As of 0.16 the engine's read and write methods return promises, so a store can
+live across a network. A call left un-awaited **does not throw** — it yields a
+`Promise`, and most things you do with a Promise succeed:
+
+```js
+plur.recall(q).length     // undefined, not an error
+{...plur.status()}        // {}
+plur.learn(x)             // resolves later, or never
+```
+
+TypeScript catches every one of these. JavaScript catches none of them, which
+is what this tool is for.
+
+## What it will and won't rewrite
+
+It rewrites only where adding `await` is unambiguous, and **parenthesises when
+the result is consumed**:
+
+```js
+const n = plur.list().length      →  const n = (await plur.list()).length
+```
+
+`await plur.list().length` would parse as `await (plur.list().length)` — it
+awaits `undefined` and yields `undefined`. Getting that wrong produces code
+that runs and returns a plausible value.
+
+It reports, but refuses to rewrite:
+
+- **calls inside `Promise.race` / `Promise.all` arrays** — awaiting there
+  settles the call *before* the combinator sees it. This silently disabled a 5s
+  timeout guard in PLUR's own CLI, and the test suite stayed green.
+- **concise arrow bodies** — the enclosing function has to become `async` first.
+- **calls whose result is consumed across multiple lines.**
+
+It never touches string literals or comments. An early version of the codemod
+that migrated PLUR itself rewrote a CLI help string into `hook-await inject`
+and a user-facing message into "Add a remote with `await plur.sync(...)`" —
+both valid TypeScript, both shipped.
+
+## Exit codes
+
+`0` clean, or all findings fixed. `2` when something needs a human — so it
+composes in CI.
+
+## Scope
+
+Only methods that became async **in 0.16**. `recallHybrid` and friends were
+always async — an un-awaited call there was already a bug. `capture` and
+`timeline` are still synchronous.

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Find PLUR calls that stopped being synchronous in 0.16 and were never awaited.
+ *
+ * ## Why this reports rather than rewrites, by default
+ *
+ * The 0.16 migration inside this repo was done with codemods over ~1,100 call
+ * sites, and they were wrong in instructive ways before they were right. Every
+ * class of mistake they made is guarded for here, because a tool that silently
+ * corrupts a user's source is worse than no tool:
+ *
+ *   - **String literals.** An early pass rewrote text inside quotes, turning a
+ *     CLI's help output into `hook-await inject` and a user-facing message into
+ *     "Add a remote with await plur.sync(...)". Both were valid TypeScript and
+ *     both shipped through a green test suite.
+ *   - **`Promise.race` / `Promise.all` arrays.** Inserting `await` into an
+ *     element resolves that call BEFORE the array is constructed, which
+ *     silently disabled a 5s timeout guard — the racing promise was already
+ *     settled. Still valid, still green.
+ *   - **ASI hazards.** A line beginning `(await ...)` after a line with no
+ *     semicolon parses as a call on the previous expression.
+ *
+ * The compiler catches an un-awaited promise in TypeScript. It cannot catch any
+ * of the above, and neither can a test suite. So: report everything, and only
+ * rewrite the sites where the transformation is unambiguous.
+ */
+/**
+ * Methods on `Plur` that return a promise as of 0.16 and did not before.
+ *
+ * Deliberately NOT a list of "every async method" — `recallHybrid`,
+ * `injectHybrid` and friends were always async, so a call to them without
+ * `await` was already a bug and is not this migration's business.
+ *
+ * `capture` and `timeline` are absent because they are still synchronous: they
+ * are backed by `episodes.yaml`, not the engram store. `suggestScope`,
+ * `dismissScope`, `reofferScopes` and `listImportSources` are absent because
+ * they were briefly async before release and were reverted.
+ */
+declare const NEWLY_ASYNC: readonly ["compact", "episodeToEngram", "getById", "ingest", "inject", "installPack", "learn", "list", "listPinned", "listStores", "outboxCount", "purgeTensions", "recall", "receipt", "recordTensions", "reindex", "rerankerEvalStatus", "resolveTension", "saveMetaEngrams", "setPinned", "status", "sync", "updateEngram", "feedback", "flushOutbox", "forget", "learnBatch", "learnRouted"];
+interface Finding {
+    file: string;
+    line: number;
+    column: number;
+    method: string;
+    /** The source line, trimmed. */
+    text: string;
+    /** True when this site can be rewritten mechanically. */
+    fixable: boolean;
+    /** Why it is not fixable, when it is not. */
+    reason?: string;
+    /**
+     * End column (1-based, exclusive) of the call expression, when the result is
+     * immediately consumed and the insertion therefore needs parentheses.
+     *
+     * `await plur.list().length` parses as `await (plur.list().length)` — it
+     * awaits `undefined` and yields `undefined`. The correct rewrite is
+     * `(await plur.list()).length`. Getting this wrong produces code that runs,
+     * returns a plausible value, and is silently incorrect — the same failure
+     * class this whole tool exists to catch.
+     */
+    wrapTo?: number;
+}
+/**
+ * Scan one file's source for un-awaited calls to newly-async methods.
+ *
+ * Matches `<receiver>.<method>(` where the receiver is any identifier or member
+ * expression — this cannot know that the receiver is a `Plur`, so it reports
+ * `db.list()` too. That is the correct trade for a text tool: a false positive
+ * costs a glance, a false negative ships a silent bug. The report says which
+ * receiver it saw so the reader can dismiss it instantly.
+ *
+ * Receiver chains may include single-level bracket indexes — `stores[0]`,
+ * `byName['team']`, `pool[i + 1]`, `arr?.[0]` — because arrays/maps of stores
+ * are ordinary shapes for this API and a receiver the regex cannot see is a
+ * call the user is never told about (the 0.16.0 audit found `arr[0].learn(x)`
+ * scanned clean, #752; its second pass found `arr?.[0].learn(x)` still did).
+ * Two index shapes remain documented misses: a NESTED index
+ * (`m[a[0]].learn(x)`) and an index whose string key contains `]`
+ * (`m["a]b"].learn(x)`) — `[^\]]` cannot span the inner `]`, and every
+ * partial interpretation fails to reach the method dot, so both are missed —
+ * not misreported, and never rewritten at the wrong offset.
+ */
+declare function scanSource(file: string, src: string, methods?: readonly string[]): Finding[];
+/**
+ * Add `await` at the fixable sites. Returns the new source and a count.
+ *
+ * Applied right-to-left so earlier offsets stay valid, and only to sites the
+ * scanner marked fixable.
+ */
+declare function applyFixes(src: string, findings: Finding[]): {
+    src: string;
+    applied: number;
+};
+
+declare function run(argv: string[]): number;
+
+export { NEWLY_ASYNC, applyFixes, run, scanSource };

package/dist/index.js

@@ -0,0 +1,464 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync, writeFileSync, readdirSync, statSync } from "fs";
+import { join, relative, extname } from "path";
+
+// src/scan.ts
+var NEWLY_ASYNC = [
+  // Derived from git, not from memory: these are the methods whose signature
+  // went sync -> async in 0.16. `packages/migrate/test/method-list.test.ts`
+  // re-derives the same set from `Plur` and fails if this drifts — the list was
+  // hand-written once and was wrong in both directions (it advised `await` on a
+  // synchronous `addStore`, and missed eight methods entirely).
+  "compact",
+  "episodeToEngram",
+  "getById",
+  "ingest",
+  "inject",
+  "installPack",
+  "learn",
+  "list",
+  "listPinned",
+  "listStores",
+  "outboxCount",
+  "purgeTensions",
+  "recall",
+  "receipt",
+  "recordTensions",
+  "reindex",
+  "rerankerEvalStatus",
+  "resolveTension",
+  "saveMetaEngrams",
+  "setPinned",
+  "status",
+  "sync",
+  "updateEngram",
+  // Already async before 0.16, so an un-awaited call was always a bug rather
+  // than migration fallout — but reporting it costs nothing and helps, and
+  // these were in the original list. `addStore` was too and is REMOVED: it is
+  // synchronous, so the tool was telling users to add an `await` that does not
+  // belong.
+  "feedback",
+  "flushOutbox",
+  "forget",
+  "learnBatch",
+  "learnRouted"
+];
+function literalSpans(src) {
+  const spans = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "/" && src[i + 1] === "/") {
+      const end = src.indexOf("\n", i);
+      spans.push([i, end === -1 ? src.length : end]);
+      i = end === -1 ? src.length : end;
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "*") {
+      const end = src.indexOf("*/", i + 2);
+      spans.push([i, end === -1 ? src.length : end + 2]);
+      i = end === -1 ? src.length : end + 2;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      const quote = c;
+      let j = i + 1;
+      while (j < src.length) {
+        if (src[j] === "\\") {
+          j += 2;
+          continue;
+        }
+        if (src[j] === quote) break;
+        j++;
+      }
+      spans.push([i, Math.min(j + 1, src.length)]);
+      i = j + 1;
+      continue;
+    }
+    if (c === "`") {
+      let j = i + 1;
+      let chunkStart = i;
+      while (j < src.length) {
+        if (src[j] === "\\") {
+          j += 2;
+          continue;
+        }
+        if (src[j] === "`") break;
+        if (src[j] === "$" && src[j + 1] === "{") {
+          spans.push([chunkStart, j]);
+          let depth = 1;
+          let k = j + 2;
+          while (k < src.length && depth > 0) {
+            if (src[k] === "{") depth++;
+            else if (src[k] === "}") depth--;
+            k++;
+          }
+          j = k;
+          chunkStart = k;
+          continue;
+        }
+        j++;
+      }
+      spans.push([chunkStart, Math.min(j + 1, src.length)]);
+      i = j + 1;
+      continue;
+    }
+    i++;
+  }
+  return spans;
+}
+function inSpans(spans, idx) {
+  for (const [a, b] of spans) if (idx >= a && idx < b) return true;
+  return false;
+}
+var ASI_SAFE_BEFORE_PAREN = /* @__PURE__ */ new Set([
+  ";",
+  "{",
+  ",",
+  "(",
+  "[",
+  ":",
+  "=",
+  ">",
+  "&",
+  "|",
+  "+",
+  "-",
+  "*",
+  "%",
+  "<",
+  "~",
+  "^",
+  "?"
+]);
+function spanAt(spans, idx) {
+  for (const s of spans) if (idx >= s[0] && idx < s[1]) return s;
+  return null;
+}
+function lastSignificantChar(src, from, spans) {
+  for (let j = from; j >= 0; j--) {
+    const span = spanAt(spans, j);
+    if (span) {
+      if (src[span[0]] === "/") {
+        j = span[0];
+        continue;
+      }
+      return src[j];
+    }
+    if (/\s/.test(src[j])) continue;
+    return src[j];
+  }
+  return null;
+}
+function positionOf(src, idx) {
+  const before = src.slice(0, idx);
+  const line = before.split("\n").length;
+  const lineStart = before.lastIndexOf("\n") + 1;
+  const lineEnd = src.indexOf("\n", idx);
+  return {
+    line,
+    column: idx - lineStart + 1,
+    text: src.slice(lineStart, lineEnd === -1 ? src.length : lineEnd).trim()
+  };
+}
+var CONTROL_KEYWORDS = /* @__PURE__ */ new Set(["if", "for", "while", "switch", "catch", "with", "do"]);
+function insideCombinatorArray(src, idx, spans) {
+  let square = 0, round = 0, curly = 0;
+  for (let i = idx - 1; i >= 0; i--) {
+    if (inSpans(spans, i)) continue;
+    const c = src[i];
+    if (c === "]") {
+      square++;
+      continue;
+    }
+    if (c === ")") {
+      round++;
+      continue;
+    }
+    if (c === "}") {
+      curly++;
+      continue;
+    }
+    if (c === ")" || c === "}") continue;
+    if (c === "[") {
+      if (square > 0) {
+        square--;
+        continue;
+      }
+      let before = "";
+      for (let j = i - 1; j >= 0 && before.length < 60; j--) {
+        if (inSpans(spans, j)) continue;
+        before = src[j] + before;
+      }
+      return /Promise\s*\.\s*(all|race|allSettled|any)\s*\(\s*$/.test(before);
+    }
+    if (c === "(") {
+      if (round > 0) {
+        round--;
+        continue;
+      }
+      return false;
+    }
+    if (c === "{") {
+      if (curly > 0) {
+        curly--;
+        continue;
+      }
+      return false;
+    }
+  }
+  return false;
+}
+function enclosingFunctionKind(src, idx, spans) {
+  let depth = 0;
+  for (let i = idx - 1; i >= 0; i--) {
+    if (inSpans(spans, i)) continue;
+    const c = src[i];
+    if (c === "}") {
+      depth++;
+      continue;
+    }
+    if (c !== "{") continue;
+    if (depth > 0) {
+      depth--;
+      continue;
+    }
+    const header = src.slice(Math.max(0, i - 220), i);
+    const fn = /(?:^|[^\w$])(async\s+)?function\s*\*?\s*[\w$]*\s*\([^()]*\)\s*$/.exec(header);
+    if (fn) return fn[1] ? "async" : "sync";
+    const arrow = /(?:^|[^\w$])(async\s*)?\([^()]*\)\s*=>\s*$/.exec(header);
+    if (arrow) return arrow[1] ? "async" : "sync";
+    const bareArrow = /(?:^|[^\w$])(async\s+)?[\w$]+\s*=>\s*$/.exec(header);
+    if (bareArrow) return bareArrow[1] ? "async" : "sync";
+    const method = /(?:^|[^\w$])(async\s+)?([\w$]+)\s*\([^()]*\)\s*$/.exec(header);
+    if (method && !CONTROL_KEYWORDS.has(method[2])) return method[1] ? "async" : "sync";
+    depth = 0;
+  }
+  return "top-level";
+}
+function isEsm(file, src) {
+  if (/\.(mjs|mts|ts|tsx)$/.test(file)) return true;
+  if (/\.(cjs|cts)$/.test(file)) return false;
+  return /^\s*(import\s|export\s|import\()/m.test(src);
+}
+function scanSource(file, src, methods = NEWLY_ASYNC) {
+  const spans = literalSpans(src);
+  const out = [];
+  const alt = methods.join("|");
+  const re = new RegExp(String.raw`([A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*|(?:\?\.)?\[[^\]\n]*\])*)\??\.(${alt})\s*(?:\?\.)?\s*\(`, "g");
+  let m;
+  while (m = re.exec(src)) {
+    const idx = m.index;
+    if (inSpans(spans, idx)) continue;
+    const before = src.slice(Math.max(0, idx - 80), idx);
+    if (/\b(await|yield)\s*$/.test(before)) continue;
+    if (/\breturn\s*$/.test(before)) continue;
+    if (/\bvoid\s*$/.test(before)) continue;
+    const after = src.slice(idx);
+    const callEnd = matchParen(after, m[0].length - 1, spans, idx);
+    if (callEnd > 0 && /^\s*\.(then|catch|finally)\s*\(/.test(after.slice(callEnd))) continue;
+    const pos = positionOf(src, idx);
+    let fixable = true;
+    let reason;
+    if (insideCombinatorArray(src, idx, spans)) {
+      fixable = false;
+      reason = "inside a Promise combinator array \u2014 awaiting here settles the call before the combinator sees it";
+    } else if (/=>\s*$/.test(before)) {
+      fixable = false;
+      reason = "concise arrow body \u2014 the enclosing function must become async first";
+    } else {
+      const kind = enclosingFunctionKind(src, idx, spans);
+      if (kind === "sync") {
+        fixable = false;
+        reason = "the enclosing function is not `async` \u2014 make it async first, then re-run";
+      } else if (kind === "top-level" && !isEsm(file, src)) {
+        fixable = false;
+        reason = "top-level await needs an ES module \u2014 convert the file, or wrap the call in an async function";
+      }
+    }
+    let wrapTo;
+    if (callEnd < 0) {
+      fixable = false;
+      reason = "could not determine where the call ends \u2014 add `await` by hand";
+    } else if (callEnd > 0 && /^\s*[.[]/.test(after.slice(callEnd))) {
+      const endIdx = idx + callEnd;
+      const endPos = positionOf(src, endIdx);
+      if (endPos.line === pos.line) wrapTo = endPos.column;
+      else {
+        fixable = false;
+        reason = "result is consumed by a multi-line call \u2014 needs `(await ...)` by hand";
+      }
+    }
+    if (fixable && wrapTo !== void 0) {
+      const lineStart = idx - (pos.column - 1);
+      if (/^\s*$/.test(src.slice(lineStart, idx))) {
+        const prev = lastSignificantChar(src, lineStart - 1, spans);
+        if (prev !== null && !ASI_SAFE_BEFORE_PAREN.has(prev)) {
+          fixable = false;
+          reason = "previous line has no terminator \u2014 a leading `(await ...)` splices onto it (ASI); end it with `;` or add `(await ...)` by hand";
+        }
+      }
+    }
+    out.push({ file, line: pos.line, column: pos.column, method: m[2], text: pos.text, fixable, reason, wrapTo });
+  }
+  return out;
+}
+function matchParen(s, open, spans, base) {
+  if (open < 0) return -1;
+  let d = 0;
+  for (let i = open; i < s.length; i++) {
+    if (inSpans(spans, base + i)) continue;
+    if (s[i] === "(") d++;
+    else if (s[i] === ")") {
+      d--;
+      if (d === 0) return i + 1;
+    }
+  }
+  return -1;
+}
+function applyFixes(src, findings) {
+  const lines = src.split("\n");
+  const fixable = findings.filter((f) => f.fixable).sort((a, b) => b.line - a.line || b.column - a.column);
+  let applied = 0;
+  for (const f of fixable) {
+    const li = f.line - 1;
+    const line = lines[li];
+    if (line === void 0) continue;
+    const at = f.column - 1;
+    if (at < 0 || at > line.length) continue;
+    if (f.wrapTo !== void 0) {
+      const end = f.wrapTo - 1;
+      if (end <= at || end > line.length) continue;
+      lines[li] = line.slice(0, at) + "(await " + line.slice(at, end) + ")" + line.slice(end);
+    } else {
+      lines[li] = line.slice(0, at) + "await " + line.slice(at);
+    }
+    applied++;
+  }
+  return { src: lines.join("\n"), applied };
+}
+
+// src/index.ts
+var HELP = `plur-migrate \u2014 find PLUR calls left un-awaited by the 0.16 async migration
+
+USAGE
+  npx @plur-ai/migrate [path]           report un-awaited calls (default: .)
+  npx @plur-ai/migrate [path] --write   also apply the unambiguous fixes
+
+WHY
+  As of 0.16 the PLUR engine's read and write methods return promises, so a
+  store can live across a network. A call left un-awaited does not throw \u2014 it
+  yields a Promise, and most property reads on a Promise succeed:
+
+      plur.recall(q).length        -> undefined, not an error
+      {...plur.status()}           -> {}
+
+  TypeScript catches all of it. JavaScript does not, which is what this is for.
+
+OPTIONS
+  --write        apply fixes (default: report only)
+  --ext .ts,.js  file extensions to scan (default: .ts,.tsx,.js,.mjs,.cjs)
+  --help         this
+`;
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", ".git", "coverage", ".next"]);
+var PREFILTER = new RegExp(String.raw`\.(?:${NEWLY_ASYNC.join("|")})\s*\(`);
+function walk(dir, exts, out = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      walk(p, exts, out);
+    } else if (exts.has(extname(e.name))) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+function run(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  const write = argv.includes("--write");
+  const extIdx = argv.indexOf("--ext");
+  const exts = new Set(
+    extIdx >= 0 && argv[extIdx + 1] ? argv[extIdx + 1].split(",").map((s) => s.startsWith(".") ? s : `.${s}`) : [".ts", ".tsx", ".js", ".mjs", ".cjs"]
+  );
+  const root = argv.find((a, i) => !a.startsWith("-") && argv[i - 1] !== "--ext") ?? ".";
+  let files;
+  try {
+    files = statSync(root).isDirectory() ? walk(root, exts) : [root];
+  } catch {
+    process.stderr.write(`plur-migrate: cannot read ${root}
+`);
+    return 1;
+  }
+  const all = [];
+  let changed = 0;
+  for (const f of files) {
+    let src;
+    try {
+      src = readFileSync(f, "utf8");
+    } catch {
+      continue;
+    }
+    if (!PREFILTER.test(src)) continue;
+    const findings = scanSource(relative(process.cwd(), f) || f, src);
+    if (findings.length === 0) continue;
+    all.push(...findings);
+    if (write) {
+      const { src: next, applied } = applyFixes(src, findings);
+      if (applied > 0) {
+        writeFileSync(f, next);
+        changed++;
+      }
+    }
+  }
+  if (all.length === 0) {
+    process.stdout.write("plur-migrate: no un-awaited PLUR calls found.\n");
+    return 0;
+  }
+  const fixable = all.filter((f) => f.fixable);
+  const manual = all.filter((f) => !f.fixable);
+  for (const f of all) {
+    const mark = f.fixable ? write ? "fixed  " : "fixable" : "MANUAL ";
+    process.stdout.write(`${mark} ${f.file}:${f.line}:${f.column}  .${f.method}()
+         ${f.text}
+`);
+    if (f.reason) process.stdout.write(`         ^ ${f.reason}
+`);
+  }
+  process.stdout.write("\n");
+  if (write) {
+    process.stdout.write(`plur-migrate: applied ${fixable.length} fix(es) across ${changed} file(s).
+`);
+  } else {
+    process.stdout.write(`plur-migrate: ${fixable.length} fixable, ${manual.length} need a human. Re-run with --write to apply the fixable ones.
+`);
+  }
+  if (manual.length > 0) {
+    process.stdout.write(
+      `
+${manual.length} site(s) are NOT rewritten on purpose. Inserting \`await\` there changes
+program meaning rather than just adding a wait \u2014 the notes above say how.
+`
+    );
+  }
+  return manual.length > 0 ? 2 : 0;
+}
+var invokedDirectly = process.argv[1] && /plur-migrate|migrate[/\\]dist[/\\]index\.js$/.test(process.argv[1]);
+if (invokedDirectly) process.exit(run(process.argv.slice(2)));
+export {
+  NEWLY_ASYNC,
+  applyFixes,
+  run,
+  scanSource
+};

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@plur-ai/migrate",
+  "version": "0.16.0",
+  "description": "Find and fix un-awaited PLUR calls after the 0.16 async migration",
+  "type": "module",
+  "bin": {
+    "plur-migrate": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}