@lorekit/cli 1.28.0 → 1.29.1

package/src/store/ttl.mjs

@@ -11,6 +11,14 @@
 //     `ttl_days` when both are supplied (the RPC's tri-state precedence).
 //   - a read filters an expired row out lazily (there is no purge daemon
 //     offline), exactly as the remote read paths do.
+//
+// `resolveDefaultTtlDays` is the one piece here with NO server counterpart, by
+// design. It answers "what TTL did the user configure for a write that named
+// none?" — a client-side policy question. The server contract is untouched:
+// omitting `ttl_*` on `memory.write` still means the row is permanent, so an
+// agent talking straight to the MCP endpoint is unaffected by a config file it
+// cannot see. That asymmetry is deliberate; moving the default server-side would
+// silently change what "omitted" means for every existing caller.
 
 export const TTL_MIN_DAYS = 1;
 export const TTL_MAX_DAYS = 365;
@@ -55,6 +63,76 @@ export function isLive(entry, now = new Date()) {
   return !entry.archived_at && !isExpired(entry.expires_at, now);
 }
 
+// The DEFAULT TTL for a write that named none, resolved from the config layers
+// (`ttl.default` and `scope.defaults.<prefix>.ttl_days` — see control.mjs).
+//
+// Returns the number of days, or null for "no default; the memory is permanent".
+//
+// Two rules that matter more than they look:
+//
+//   1. LONGEST MATCHING PREFIX WINS, not first-declared. `scope.defaults` is a
+//      plain object, so declaration order is whatever the author's editor left
+//      behind; a `branch::` entry and a `branch::owner/repo::` entry must resolve
+//      deterministically, and the more specific one is the one the author meant.
+//      (`tagsHint` UNIONS every match instead — correct there, because tags
+//      accumulate and a TTL cannot.)
+//   2. AN EXPLICIT `null` MEANS PERMANENT and outranks `ttl.default`. Without it
+//      a repo-wide default could not be switched off for the one scope that
+//      holds durable lore, and `"ttl_days": null` is the only honest spelling of
+//      "keep this forever" — omitting the key has to keep meaning "inherit".
+//
+// Total by contract: a malformed config (fractional days, a string, out of
+// range, a non-object entry) yields null rather than throwing. A config file is
+// not a caller assertion the way `--ttl-days` is — it is ambient state that must
+// never be able to break an unrelated write, the same posture the hook engine
+// takes toward the host agent.
+export function resolveDefaultTtlDays(scope, { ttlDefault = null, scopeDefaults = null } = {}) {
+  if (typeof scope === 'string' && scope && scopeDefaults && typeof scopeDefaults === 'object') {
+    let bestPrefix = null;
+    let bestValue;
+    for (const [prefix, cfg] of Object.entries(scopeDefaults)) {
+      if (!cfg || typeof cfg !== 'object' || !('ttl_days' in cfg)) continue;
+      if (!matchesScopePrefix(scope, prefix)) continue;
+      if (bestPrefix !== null && prefix.length <= bestPrefix.length) continue;
+      bestPrefix = prefix;
+      bestValue = cfg.ttl_days;
+    }
+    if (bestPrefix !== null) {
+      if (bestValue === null) return null; // explicit "permanent" for this scope
+      return safeTtlDays(bestValue);
+    }
+  }
+  return safeTtlDays(ttlDefault);
+}
+
+// Whether a write's resolved scope falls under a `scope.defaults` key. An exact
+// match, or a `::`-delimited descendant — so `repo::owner` never captures
+// `repo::owner-other/x`. Shared with the nudge's tags hint so the two cannot
+// disagree about what "this scope is configured" means.
+export function matchesScopePrefix(scope, prefix) {
+  if (typeof scope !== 'string' || typeof prefix !== 'string' || !prefix) return false;
+  if (scope === prefix) return true;
+  return scope.startsWith(prefix.endsWith('::') ? prefix : prefix + '::');
+}
+
+// parseTtlDays, but a rejected value degrades to null instead of throwing.
+//
+// The type guard is not redundant with parseTtlDays: that one coerces with
+// Number(), which maps `true` to 1 and `[]` to 0 — fine for a flag the user
+// typed (a CLI flag is always a string), a footgun for a JSON value where `true`
+// is a plausible typo for "yes, expire these" and would silently mean ONE DAY.
+// Only a number or a numeric string is a TTL here.
+function safeTtlDays(value) {
+  if (typeof value !== 'number' && !(typeof value === 'string' && value.trim() !== '')) {
+    return null;
+  }
+  try {
+    return parseTtlDays(value);
+  } catch {
+    return null;
+  }
+}
+
 // Resolve a write's `expires_at` from the tri-state TTL inputs, mirroring
 // memory_write (00030/00031): `clearTtl` wins (→ permanent, and `ttlDays` is
 // never even validated); else a supplied `ttlDays` sets expiry from `now`; else

package/src/write.mjs

@@ -13,7 +13,8 @@
 //   --tags <a,b,c>         Comma-separated tag list (default: no tags)
 //   --source-agent <name>  Which agent recorded this lesson (default: none)
 //   --trigger <slug>       What prompted the write (default: none)
-//   --ttl-days <n>         Days until the memory auto-expires (1–365)
+//   --ttl-days <n>         Days until the memory auto-expires (1–365). When
+//                          omitted, a configured default may apply — see below.
 //   --clear-ttl            Remove any existing expiry (make the memory permanent)
 //   --org <slug>           Write to this org (remote only)
 //
@@ -27,6 +28,15 @@
 //   --origin-pr <n>             The pull request this lesson came out of
 //   --no-origin                 Record no provenance at all
 //
+// Default TTL. A write that passes neither --ttl-days nor --clear-ttl picks up
+// whatever the config layers configured for its scope (`ttl.default` and
+// `scope.defaults.<prefix>.ttl_days`; see control.mjs). Precedence is explicit
+// flag > config > permanent, so a flag is always the last word and --clear-ttl
+// is how you say "permanent" against a repo that defaults to expiring. The
+// resolved source is reported in the confirmation line and on the telemetry
+// span, because a TTL nobody typed is exactly the kind of thing that should
+// never be silent.
+//
 // Store targeting (default: remote if configured, else local):
 //   --remote               Force write to the remote store
 //   --local                Force write to the local offline store
@@ -39,12 +49,12 @@
 // false = updated) when the remote reports it.
 import process from 'node:process';
 import { resolveProjectRoot } from './config.mjs';
-import { resolveDenies } from './control.mjs';
+import { loadControl, resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
 import { log, err, heading, status, c } from './util.mjs';
 import { parseScopeKey } from './lessons-view.mjs';
 import { deriveOrigin, mergeOrigin } from './origin.mjs';
-import { parseTtlDays } from './store/ttl.mjs';
+import { parseTtlDays, resolveDefaultTtlDays } from './store/ttl.mjs';
 
 // Read all of stdin to a string. Resolves to '' when stdin IS a TTY (no pipe).
 function readStdin() {
@@ -132,6 +142,34 @@ export async function write(args) {
     }
   }
   const clearTtl = Boolean(args['clear-ttl']);
+
+  // Neither flag given → fall back to the scope's configured default, if any.
+  // `--clear-ttl` deliberately suppresses it: "make this permanent" has to mean
+  // permanent, not "permanent unless the repo config disagrees". Config is read
+  // through the same loadControl the hooks use, so the default the nudge advises
+  // and the default this command applies can never diverge.
+  let ttlSource = ttlDays ? 'flag' : 'none';
+  if (ttlDays === undefined && !clearTtl) {
+    const configured = resolveDefaultTtlDays(scope, loadControl(root, { env }));
+    if (configured != null) {
+      ttlDays = configured;
+      ttlSource = 'config';
+    }
+  }
+
+  // What gets REPORTED is the outcome, not the input. `--clear-ttl` beats
+  // `--ttl-days` inside resolveExpiresAt (and in memory_write, migrations
+  // 00030/00031), so `--ttl-days 7 --clear-ttl` persists a permanent row —
+  // yet ttlDays/ttlSource still described the flag the user typed, so the
+  // human output claimed "expires in 7 days" and --json reported
+  // ttl_days 7 / ttl_source "flag" for a row whose expires_at is null.
+  // Kept separate from ttlDays on purpose: writeArgs below spreads
+  // `...(ttlDays ? { ttl_days } : {})`, and nulling ttlDays itself would
+  // silently stop sending ttl_days to the remote RPC — a wire change nobody
+  // asked for. The precedence lives in one place; this only mirrors it.
+  const reportedTtlDays = clearTtl ? null : (ttlDays ?? null);
+  const reportedTtlSource = clearTtl ? 'none' : ttlSource;
+
   const orgSlug = typeof args.org === 'string' ? args.org : undefined;
 
   // ── Provenance ────────────────────────────────────────────────────────────
@@ -254,6 +292,8 @@ export async function write(args) {
       tags,
       source_agent: sourceAgent || null,
       trigger: trigger || null,
+      ttl_days: reportedTtlDays,
+      ttl_source: reportedTtlSource,
       origin,
     }, null, 2));
   } else {
@@ -263,6 +303,13 @@ export async function write(args) {
     log(`  ${c.dim('scope')}  ${scope}`);
     log(`  ${c.dim('key')}    ${key}`);
     if (tags.length) log(`  ${c.dim('tags')}   ${tags.join(', ')}`);
+    // Name the source. A TTL the caller typed needs no explanation; one that came
+    // from a config file two directories up does, or the first surprise is a
+    // memory that quietly vanished.
+    if (reportedTtlDays) {
+      const suffix = reportedTtlSource === 'config' ? c.dim(' (from config)') : '';
+      log(`  ${c.dim('expires')} in ${reportedTtlDays} day${reportedTtlDays === 1 ? '' : 's'}${suffix}`);
+    }
     status('pass', verb, `${scope}::${key}`);
     log('');
   }
@@ -272,7 +319,8 @@ export async function write(args) {
     'lorekit.cli.write.store': storeName,
     'lorekit.cli.write.inserted': inserted,
     'lorekit.cli.write.has_tags': tags.length > 0,
-    'lorekit.cli.write.has_ttl': Boolean(ttlDays),
+    'lorekit.cli.write.has_ttl': Boolean(reportedTtlDays),
+    'lorekit.cli.write.ttl_source': reportedTtlSource,
     'lorekit.cli.write.clear_ttl': clearTtl,
   };
 }