@lorekit/cli 1.50.0 → 1.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/mcp.mjs

@@ -158,6 +158,30 @@ export function normalizeRunEnvironment(raw) {
   return /^[A-Za-z0-9_.\-:]+$/.test(t) ? t : null;
 }
 
+/**
+ * The retry delay a failed response advertised, in whole seconds, or null.
+ *
+ * Prefers the JSON body's `retryAfterSeconds` over the `Retry-After` header:
+ * both are set by the same `tooManyRequests()` helper, and the body value is
+ * the number the rate-limit RPC actually returned, while the header is its
+ * stringified copy that an intermediary may rewrite.
+ *
+ * TOTAL over any input. `headers` is read through optional calls because a
+ * test double (and a hand-rolled Response-alike) may not implement the Headers
+ * interface, and a missing retry hint must never be able to throw on an error
+ * path — the caller is already handling a failure.
+ */
+export function retryAfterFrom(data, headers) {
+  const raw = data?.retryAfterSeconds ?? (typeof headers?.get === 'function' ? headers.get('retry-after') : null);
+  if (raw == null || raw === '') return null;
+  const n = Number(raw);
+  // A `Retry-After` may also be an HTTP-date; a non-numeric value is reported
+  // as "no hint" so the caller falls back to its own backoff rather than
+  // waiting on NaN.
+  if (!Number.isFinite(n) || n < 0) return null;
+  return Math.ceil(n);
+}
+
 export async function restFetch(baseUrl, token, path, { method = 'GET', body, timeoutMs = 10000, traceparent } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -203,6 +227,12 @@ export async function restFetch(baseUrl, token, path, { method = 'GET', body, ti
       return {
         ok: false,
         httpStatus: res.status,
+        // How long the server asked the caller to wait, in seconds, or null when
+        // it did not say. Only a 429 carries one today (`tooManyRequests` sets
+        // BOTH a `retryAfterSeconds` body field and the `Retry-After` header),
+        // but this is read on every failure so a future 503 needs no change
+        // here. Additive: existing callers ignore the extra key.
+        retryAfter: retryAfterFrom(data, res.headers),
         error: data?.error ? { message: data.error, code: data.code } : { code: res.status, message: text.slice(0, 200) || res.statusText },
       };
     }

package/src/store/format.mjs

@@ -29,7 +29,7 @@ export const FIELDS = [
   // columns: a file written before this existed simply decodes it as absent.
   'expires_at',
   // Recurrence — how many times this lesson has been written, mirroring the
-  // hosted `memories.seen_count` column (migration 00058) so an offline store
+  // hosted `memories.seen_count` column (migration 00059) so an offline store
   // carries the same salience signal a remote one does. Appended like the
   // columns above: a file written before this existed decodes it as absent,
   // which the read projection reports as 0 rather than inventing a count.

package/src/store/local.mjs

@@ -134,7 +134,7 @@ class LocalStore {
       archived_at: null,
       expires_at,
       // Recurrence, counted the way the hosted `memory_write` RPC counts it
-      // (migration 00058): a write against a key this store already holds IS
+      // (migration 00059): a write against a key this store already holds IS
       // the next sighting. `seenCountOf` floors an absent/hand-edited value to
       // 0, so a file written before this column existed resumes at 1 on its
       // next write rather than throwing or restarting the tally at 2.

package/src/store/remote.mjs

@@ -21,6 +21,7 @@
 import { restFetch, mcpToRestBase } from '../mcp.mjs';
 import { getActiveTraceparent } from '../telemetry.mjs';
 import { withReadFields } from './entry-fields.mjs';
+import { normalizeCreatedAt } from './created-at.mjs';
 
 // Drop undefined/null args so JSON payloads stay tidy.
 function stripUndefined(obj) {
@@ -29,6 +30,55 @@ function stripUndefined(obj) {
   return out;
 }
 
+/**
+ * A read that could not be answered — a transport failure or a non-2xx status,
+ * as opposed to "the lesson is not there".
+ *
+ * Exported so a caller can tell it from a programming error and degrade
+ * per-entry (report this one, keep going) instead of aborting a whole run.
+ * `result` carries the raw store envelope for the message the caller shows.
+ */
+export class StoreReadError extends Error {
+  constructor(message, result) {
+    super(message);
+    this.name = 'StoreReadError';
+    this.result = result;
+  }
+}
+
+// An absolute `expires_at` expressed as the hosted write's relative `ttl_days`.
+//
+// Three outcomes, and the third exists because "no expiry" and "I cannot tell"
+// must not collapse into one answer:
+//
+//   `undefined`  no expiry — the caller states that positively with
+//                `clear_ttl: true`, so a permanent lesson stops being expiring.
+//   `'expired'`  already elapsed; the caller must refuse (see `putEntry`).
+//   `'unknown'`  an unparseable value. The caller then sends NEITHER TTL field,
+//                leaving the RPC on its `'keep'` branch, because the safe
+//                reading of a corrupt frontmatter field is "do not touch the
+//                expiry" — the same fail-safe posture as `isExpired`. Treating
+//                it as no expiry would let one bad character wipe a live remote
+//                TTL.
+//
+//   else         the remaining WHOLE days, clamped to the schema's 1–365.
+function remoteTtlDays(expiresAt, now = new Date()) {
+  const exact = remoteTtlDaysExact(expiresAt, now);
+  if (typeof exact !== 'number') return exact;
+  return Math.min(365, Math.max(1, exact));
+}
+
+// The same conversion WITHOUT the 1–365 clamp, so a caller can see that the
+// clamp bound and report the loss. Same three non-numeric outcomes.
+function remoteTtlDaysExact(expiresAt, now = new Date()) {
+  if (!expiresAt) return undefined;
+  const ms = Date.parse(expiresAt);
+  if (Number.isNaN(ms)) return 'unknown';
+  const remaining = ms - now.getTime();
+  if (remaining <= 0) return 'expired';
+  return Math.ceil(remaining / 86_400_000);
+}
+
 export function createRemoteStore({ endpoint, token } = {}) {
   return new RemoteStore(endpoint, token);
 }
@@ -151,7 +201,24 @@ class RemoteStore {
     // scope+key is unique, so one row is all there can be — don't pull the default page of 50.
     p.set('limit', '1');
     const res = await this._rest(`/memories?${p}`);
-    if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
+    // `unusable` is passed through: `_rest` short-circuits an unconfigured
+    // store with that flag and NOTHING else, so a caller that drops it is left
+    // with a failure carrying no error and no networkError — a blank failure it
+    // can only report generically. Additive; every existing caller branches on
+    // `ok` and ignores the extra key.
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: res.error ?? null,
+        // Carried for the same reason `write` carries them: a read can be
+        // rate-limited too, and a caller that retries needs to tell a 429 it
+        // should wait out from one it must not.
+        httpStatus: res.httpStatus ?? null,
+        retryAfter: res.retryAfter ?? null,
+        networkError: res.networkError ?? null,
+        unusable: res.unusable ?? false,
+      };
+    }
     const entries = res.data?.entries ?? [];
     // Same projection as list/search — a single read must not answer with a
     // different shape than the listing the caller found the key in.
@@ -181,7 +248,223 @@ class RemoteStore {
     if (origin_commit !== undefined) body.origin_commit = origin_commit;
     if (origin_pr !== undefined) body.origin_pr = origin_pr;
     const res = await this._rest('/memories', { method: 'POST', body });
-    return { ok: res.ok, error: res.error, networkError: res.networkError };
+    // `httpStatus` and `retryAfter` are passed through so a caller can tell the
+    // two 429s apart and honour the server's own backoff. They are DIFFERENT
+    // failures wearing one status code: `code: 'rate_limited'` is transient and
+    // must be retried, `code: 'memory_cap'` is terminal (translateDbError maps
+    // the LK001 cap trigger to 429 as well) and must not be. Additive — the
+    // existing `{ ok, error, networkError }` keys are unchanged.
+    // Every field is coalesced, not just the retry hint: a caller comparing
+    // `httpStatus` must not get `null` from a refusal and `undefined` from the
+    // network-error or `unusable` branch, which is the exact split the shape
+    // exists to remove.
+    return {
+      ok: res.ok,
+      error: res.error ?? null,
+      httpStatus: res.httpStatus ?? null,
+      retryAfter: res.retryAfter ?? null,
+      networkError: res.networkError ?? null,
+      // `_rest` short-circuits an unconfigured store with `{ ok:false,
+      // unusable:true }` and no error at all, so without this the caller sees
+      // a failure with every field null and no reason. Passed through the way
+      // `listScopes` already does.
+      unusable: res.unusable ?? false,
+    };
+  }
+
+  // ── Migrate-destination parity with LocalStore ────────────────────────────
+  //
+  // `migrate` classifies each source entry ADD / UPDATE / NOOP with a read and
+  // then upserts it, against whatever store it was handed. LocalStore answers
+  // that with `getEntry` + `putEntry`; these are the remote halves, so the
+  // migrate loop stays ONE code path instead of branching per destination.
+  //
+  // The local pair is lossless (`putEntry` writes every field verbatim,
+  // archived rows included). The remote pair CANNOT be, because the hosted
+  // write is an RPC with a fixed parameter list, not a file write:
+  //
+  //   preserved  scope, key, source_agent, trigger, and `created` —
+  //              sent as `created_at`, which memory_write honours on INSERT
+  //              only, so a migrated lesson keeps its original creation date
+  //              and its ranking recency with it. `value` survives too but is
+  //              TRIMMED: `MemoryWriteSchema` applies `.transform(s =>
+  //              s.trim())`, so surrounding whitespace does not make the trip.
+  //   re-stamped `updated` — the server sets it to the write instant. There is
+  //              no parameter for it, and inventing one would let a client
+  //              backdate an edit it did not make.
+  //   derived    `seen_count` — the RPC owns the tally (migration 00059: a
+  //              write against an existing key IS the next sighting). A lesson
+  //              the hosted store has never seen lands at 1; one it already
+  //              holds lands at ITS count plus one, not the local one. Either
+  //              way the local history does not transfer.
+  //   converted  `expires_at` → `ttl_days`, the remaining whole days, clamped
+  //              to the schema's 1–365 (a longer-lived TTL is clamped, not
+  //              dropped — the alternative is silently making it permanent).
+  //              A clamp IS lossy, so it is reported: the result carries
+  //              `ttlClamped: true` and the caller can list the entry as
+  //              shortened rather than leaving the user to discover it.
+  //              A PERMANENT entry sends `clear_ttl: true` rather than simply
+  //              omitting `ttl_days`: omission is the RPC's `'keep'` branch
+  //              (migration 00031), which leaves an existing remote
+  //              `expires_at` in place, so a permanent local lesson would
+  //              land on an expiring remote row and still die.
+  //   authoritative
+  //              `tags`. The conflict clause is `tags = excluded.tags`, so the
+  //              source entry's list REPLACES the hosted one — an untagged
+  //              local entry sends `[]` and clears whatever labels the hosted
+  //              row carried. That is what a verbatim upsert means here (the
+  //              local file is the thing being migrated), but it is the one
+  //              field where "verbatim" can remove hosted data, so it is
+  //              called out rather than filed under preserved.
+  //   sticky     `origin_*`. The RPC's conflict clause coalesces provenance
+  //              (`coalesce(excluded.origin_repo, memories.origin_repo)`, and
+  //              likewise for branch/commit/pr) so a write that does not know
+  //              a field cannot erase what an earlier one recorded. A migrated
+  //              entry with NO provenance therefore leaves whatever the hosted
+  //              row already had; it cannot clear it, by design, and there is
+  //              no parameter that would. `source_agent` and `trigger` are NOT
+  //              coalesced (`= excluded.*`), so an absent one still CLEARS the
+  //              hosted value — not because a null is sent (`stripUndefined`
+  //              drops nulls before the request) but because the REST handler
+  //              substitutes `?? null` for the missing field and the RPC
+  //              writes that. Omitted and null are the same instruction here,
+  //              which is the opposite of what they mean for `origin_*`. `kind` and `host` are coalesced the same
+  //              way, and this store never sends them at all — the server
+  //              infers both from the `loop::` tag (`resolveKindHost`), which
+  //              the tags carry, so a migrated lesson classifies itself.
+  //
+  // Two states have no remote representation at all and are REFUSED rather
+  // than silently rewritten, because writing them would resurrect a lesson the
+  // user retired: an archived entry (every conflict predicate on `memories` is
+  // partial on `archived_at is null`, so the hosted write does not revive the
+  // archived row — it INSERTS a second, live one beside it, leaving the store
+  // with both) and
+  // an already-expired one (any `ttl_days` re-dates it into the future). Both
+  // come back as `{ ok:false, unsupported }` so the caller can report them as
+  // skipped. `migrate` does NOT filter them today — adding that filter is the
+  // job of the PR that makes a remote destination reachable — so until then
+  // this refusal is the only thing standing between an archived lesson and
+  // resurrection, which is why it lives in the store and not in the caller.
+
+  // Raw lookup by scope+key, mirroring `LocalStore.getEntry` — the entry or
+  // null. The ROW is each store's own: this answers a REST `MemoryEntry`
+  // (`created_at`/`updated_at`) and the local one answers parsed frontmatter
+  // (`created`/`updated`), both through `withReadFields`. That is deliberate —
+  // the pair exists so a caller can ASK either store whether a key is there,
+  // not so it can compare two rows field-by-field without knowing which store
+  // produced them. A caller that compares has to speak the destination's
+  // spelling; that is what the remote comparison in the migrate loop does. LocalStore's is synchronous and this one cannot be, so callers must
+  // `await` it; awaiting the local store's plain return value is a no-op.
+  //
+  // One semantic difference the caller has to know about: LocalStore.getEntry
+  // sees archived rows and this cannot — `GET /memories` filters them out — so
+  // a remote destination classifies an archived counterpart as ADD, and the
+  // write then lands as a NEW live row beside the archived one (the conflict
+  // predicates are partial on `archived_at is null`). That is what the hosted
+  // `memory_write` does for any write against an archived key, not a
+  // migrate-specific quirk — and it is why `putEntry` refuses an archived
+  // source entry outright rather than relying on this classification.
+  //
+  // A FAILED read THROWS rather than answering null. Null is the answer to "no
+  // such lesson", and a caller that classifies ADD / UPDATE / NOOP acts on it:
+  // returning null for a transient 500 or a dropped connection would quietly
+  // reclassify an existing hosted lesson as new and overwrite it. The local
+  // store never throws here (a file read that fails is genuinely a miss), so
+  // this widens the contract only where the failure mode exists.
+  async getEntry({ scope, key } = {}) {
+    const res = await this.read({ scope, key });
+    if (!res.ok) {
+      // An unconfigured store carries no error at all, so name that case
+      // rather than reporting the generic failure text for it.
+      const reason = res.unusable
+        ? 'the remote store is not configured (missing endpoint or token)'
+        : (res.networkError || res.error?.message || 'read failed');
+      throw new StoreReadError(`remote read failed for ${scope}::${key}: ${reason}`, res);
+    }
+    return res.entry ?? null;
+  }
+
+  // Upsert one entry, as close to verbatim as the hosted write allows. See the
+  // fidelity table above for exactly which fields survive.
+  //
+  // EVERY branch answers with the SAME key set — `write`'s
+  // `{ ok, error, httpStatus, retryAfter, networkError, unusable }` plus
+  // Unlike `LocalStore.putEntry`, no `entry` comes back: the hosted write
+  // returns an id and derives the rest server-side, so echoing the request as
+  // if it were the stored row would be a fabrication. A caller that needs the
+  // stored row reads it back.
+  //
+  // `unsupported` (the refusal reason, else null), `ttlClamped` (the entry
+  // landed with a shortened life) and `createdAtDropped` (its `created` was
+  // unusable, so the server stamped the write instant instead). The last two
+  // report what HAPPENED, so both are false when the write did not succeed. A refusal fills the transport fields
+  // with null rather than omitting them, so a caller reading any one key never
+  // gets a value from one branch and `undefined` from another.
+  async putEntry(entry = {}, { now = new Date() } = {}) {
+    const refuse = (unsupported, message) => ({
+      ok: false,
+      unsupported,
+      // Carries a `code` like every real failure, so a caller can branch on
+      // one field instead of matching prose.
+      error: { message, code: 'unsupported' },
+      httpStatus: null,
+      retryAfter: null,
+      networkError: null,
+      // Every key any putEntry branch answers with, so a caller reading one
+      // never gets a value from one branch and `undefined` from another.
+      unusable: false,
+      ttlClamped: false,
+      createdAtDropped: false,
+    });
+    if (entry?.archived_at) {
+      return refuse('archived', 'archived entries cannot be written remotely — the hosted write would insert a second, live row beside the archived one');
+    }
+    const ttl = remoteTtlDays(entry?.expires_at, now);
+    if (ttl === 'expired') {
+      return refuse('expired', 'expired entries cannot be written remotely — any TTL would re-date them into the future');
+    }
+    // The same validation the server applies (`_shared/created-at.ts`, mirrored
+    // here), run BEFORE the request rather than discovered as a 400. A local
+    // file can hold a hand-edited or clock-skewed `created`, and losing the
+    // whole lesson over its creation date is the wrong trade: drop the
+    // override, let the server stamp now, and report the loss so the caller
+    // can say which entries were re-dated.
+    let createdAt;
+    let createdAtDropped = false;
+    try {
+      createdAt = normalizeCreatedAt(entry?.created ?? null, now) ?? undefined;
+    } catch {
+      createdAt = undefined;
+      createdAtDropped = Boolean(entry?.created);
+    }
+    const result = await this.write(stripUndefined({
+      scope: entry.scope,
+      key: entry.key,
+      value: entry.value == null ? '' : String(entry.value),
+      tags: Array.isArray(entry.tags) ? entry.tags : [],
+      source_agent: entry.source_agent,
+      trigger: entry.trigger,
+      created_at: createdAt,
+      // `'unknown'` sends neither field, leaving the RPC on its `'keep'`
+      // branch. A real TTL sends only `ttl_days`; no TTL says so explicitly
+      // with `clear_ttl` rather than by omission — see the fidelity note above.
+      ttl_days: typeof ttl === 'number' ? ttl : undefined,
+      clear_ttl: ttl === undefined ? true : undefined,
+      origin_repo: entry.origin_repo,
+      origin_branch: entry.origin_branch,
+      origin_commit: entry.origin_commit,
+      origin_pr: entry.origin_pr,
+    }));
+    // Always present, like every other key in this envelope — a caller must
+    // not have to know which branch produced the result to read it.
+    // Both flags describe what HAPPENED, so they are false on a write that did
+    // not happen — a failed request shortened nothing and re-dated nothing.
+    return {
+      ...result,
+      unsupported: null,
+      ttlClamped: Boolean(result.ok) && ttl === 365 && remoteTtlDaysExact(entry?.expires_at, now) > 365,
+      createdAtDropped: Boolean(result.ok) && createdAtDropped,
+    };
   }
 
   // Natural-key DELETE. Without `force` the server soft-archives (stamps