@igstack/app-catalog-backend-core 0.16.0 → 0.17.1-alpha-20260821043201

package/src/modules/appCatalog/freshness.ts

@@ -2,13 +2,17 @@
  * Freshness semantic for a catalog resource.
  *
  * The backend owns this calculation so the frontend stays dumb: it just renders
- * `lastCheckedAt` and, when `isStale` is true, a muted "may be out of date" note.
+ * `lastContentChangeAt` (falling back to `lastCheckedAt`) and, when `isStale` is
+ * true, a muted "may be out of date" note.
  *
  * Data source: the autoupdate scan records, per app, when its sources were last
- * verified (`lastCheckedAt`) and when the next check is due (`nextCheckAfter`,
- * adaptive backoff). "Stale" means the entry is more than a grace period past
- * its due date — i.e. the automated freshness loop has fallen behind for this
- * app, so a human reader should treat the info with mild caution.
+ * verified (`lastCheckedAt`), when their content last actually changed
+ * (`lastContentChangeAt`), and when the next check is due (`nextCheckAfter`,
+ * adaptive backoff). The two "last" dates are deliberately distinct — a source
+ * can be re-read many times without changing, so "checked" is not "updated".
+ * "Stale" means the entry is more than a grace period past its due date — i.e.
+ * the automated freshness loop has fallen behind for this app, so a human reader
+ * should treat the info with mild caution.
  */
 
 import type { Freshness } from '../../types/common/appCatalogTypes'
@@ -18,21 +22,31 @@ export type { Freshness }
 /** A check is "stale" once it is this far past its due date (ms). Default: 7 days. */
 export const STALE_GRACE_MS = 7 * 24 * 60 * 60 * 1000
 
+/** The stored dates a resource's freshness is computed from (ISO strings). */
+export interface FreshnessInput {
+  /** When the sources were last verified — only means the schedule advanced. */
+  lastCheckedAt?: string | null
+  /** When the next check is due (adaptive backoff). */
+  nextCheckAfter?: string | null
+  /** When the source content last actually changed. Null on pre-existing rows. */
+  lastContentChangeAt?: string | null
+}
+
 /**
  * Compute the freshness semantic from the stored dates.
  *
- * @param lastCheckedAt ISO string or null — when sources were last verified.
- * @param nextCheckAfter ISO string or null — when the next check is due.
+ * @param dates the resource's stored freshness timestamps.
  * @param now current time (defaults to Date.now()); injectable for tests.
  */
 export function computeFreshness(
-  lastCheckedAt: string | null,
-  nextCheckAfter: string | null,
+  dates: FreshnessInput,
   now: number = Date.now(),
 ): Freshness {
+  const { lastCheckedAt, nextCheckAfter, lastContentChangeAt } = dates
+
   // Never checked → no line is shown at all (frontend hides null lastCheckedAt).
   if (!lastCheckedAt) {
-    return { lastCheckedAt: null, isStale: false }
+    return { lastCheckedAt: null, lastContentChangeAt: null, isStale: false }
   }
 
   let isStale = false
@@ -43,5 +57,9 @@ export function computeFreshness(
     }
   }
 
-  return { lastCheckedAt, isStale }
+  return {
+    lastCheckedAt,
+    lastContentChangeAt: lastContentChangeAt ?? null,
+    isStale,
+  }
 }

package/src/modules/appCatalog/service.ts

@@ -153,15 +153,21 @@ function rowToResource(row: ResourceRowWithSourceRefs): Resource {
       ? undefined
       : (row.deprecated as unknown as Resource['deprecated'])
   const aiPrompt = row.aiPrompt == null ? undefined : row.aiPrompt
+  const aiMemory = row.aiMemory == null ? undefined : row.aiMemory
   const urlIssues = (row.urlIssues as unknown as string[] | null)?.length
     ? (row.urlIssues as unknown as string[])
     : undefined
   const tiers =
     row.tiers == null ? undefined : (row.tiers as unknown as Resource['tiers'])
-  const freshness = computeFreshness(
-    row.lastCheckedAt ? row.lastCheckedAt.toISOString() : null,
-    row.nextCheckAfter ? row.nextCheckAfter.toISOString() : null,
-  )
+  const freshness = computeFreshness({
+    lastCheckedAt: row.lastCheckedAt ? row.lastCheckedAt.toISOString() : null,
+    nextCheckAfter: row.nextCheckAfter
+      ? row.nextCheckAfter.toISOString()
+      : null,
+    lastContentChangeAt: row.lastContentChangeAt
+      ? row.lastContentChangeAt.toISOString()
+      : null,
+  })
 
   return {
     id: row.id,
@@ -181,6 +187,7 @@ function rowToResource(row: ResourceRowWithSourceRefs): Resource {
     sources,
     deprecated,
     aiPrompt,
+    aiMemory,
     urlIssues,
     tiers,
     // Fields from former SubResource
@@ -295,6 +302,30 @@ export async function updateApp(input: UpdateAppInput): Promise<Resource> {
   return rowToResource(updated)
 }
 
+export interface UpdateAiMemoryInput {
+  /** Resource id (DB id, not slug) */
+  id: string
+  /** New value for aiMemory. Pass null to clear. */
+  aiMemory: string | null
+}
+
+/**
+ * Updates the AI-owned scratchpad for a resource.
+ * This mutation is intentionally separate from updateApp so AI agents can
+ * write knowledge without a full MR cycle. It does NOT touch aiPrompt.
+ */
+export async function updateAiMemory(
+  input: UpdateAiMemoryInput,
+): Promise<Resource> {
+  const prisma = getDbClient()
+  const updated = await prisma.dbResource.update({
+    where: { id: input.id },
+    data: { aiMemory: input.aiMemory },
+    include: { sourceRefs: true },
+  })
+  return rowToResource(updated)
+}
+
 export function deriveCategories(resources: Resource[]): AppCategory[] {
   const tagSet = new Set<string>()
   for (const resource of resources) {

package/src/modules/assets/upsertAsset.ts

@@ -21,15 +21,31 @@ export async function upsertAsset({
     originalFilename,
   })
 
-  // If an asset with the same checksum already exists, reuse it instead of storing duplicate binary.
   const existing = await prisma.dbAsset.findUnique({
     where: { name },
   })
 
   if (existing) {
-    // Reusing the stored binary must not keep a mimeType we no longer derive:
-    // rows written by an older, wrong derivation would never be corrected.
-    if (existing.mimeType !== mimeType) {
+    // The checksum is the source of truth for whether the underlying bytes
+    // changed. Reusing the stored binary on a checksum match must not keep a
+    // mimeType we no longer derive: rows written by an older, wrong
+    // derivation would never be corrected otherwise. A checksum mismatch
+    // means the file on disk was replaced with different content (e.g. an
+    // SVG swapped for a PNG) — the whole row must be rewritten, not just
+    // mimeType, or the new bytes are silently discarded forever.
+    if (existing.checksum !== checksum) {
+      await prisma.dbAsset.update({
+        where: { id: existing.id },
+        data: {
+          content: new Uint8Array(buffer),
+          checksum,
+          fileSize,
+          width,
+          height,
+          mimeType,
+        },
+      })
+    } else if (existing.mimeType !== mimeType) {
       await prisma.dbAsset.update({
         where: { id: existing.id },
         data: { mimeType },

package/src/server/controller.ts

@@ -1,5 +1,6 @@
 import {
   getAppCatalogData,
+  updateAiMemory as updateAiMemoryService,
   updateApp as updateAppService,
 } from '../modules/appCatalog/service'
 import type { AppCatalogData } from '../types'
@@ -53,6 +54,16 @@ export function createTrpcRouter(
         .mutation(async ({ input }): Promise<Resource> => {
           return updateAppService(input)
         }),
+      updateAiMemory: publicProcedure
+        .input(
+          z.object({
+            id: z.string(),
+            aiMemory: z.string().nullable(),
+          }),
+        )
+        .mutation(async ({ input }): Promise<Resource> => {
+          return updateAiMemoryService(input)
+        }),
     }),
 
     // Auth routes (requires auth instance)

package/src/types/common/appCatalogTypes.ts

@@ -46,6 +46,13 @@ export interface SourceReference {
 export interface Freshness {
   /** ISO-8601 timestamp the app's sources were last verified, or null if never. */
   lastCheckedAt: string | null
+  /**
+   * ISO-8601 timestamp the source content last actually CHANGED — what the UI
+   * shows as "Updated". Distinct from `lastCheckedAt`: a source can be re-read
+   * repeatedly without changing. Null for entries scanned before this was
+   * tracked, in which case the frontend falls back to `lastCheckedAt`.
+   */
+  lastContentChangeAt: string | null
   /** True when the entry is overdue for a re-check by more than the grace period. */
   isStale: boolean
 }
@@ -82,6 +89,8 @@ export interface Resource {
   }
   /** Agent-facing prompt guiding how to maintain this app's data */
   aiPrompt?: string
+  /** AI-owned scratchpad: strategies, gotchas, scripts, retros accumulated per app */
+  aiMemory?: string
   /** URL health issues detected by automated scanning */
   urlIssues?: string[]
   /** Optional tier variants (e.g., prod/dev) with per-tier URLs and access */
@@ -118,6 +127,7 @@ export interface Resource {
    */
   lastCheckedAt?: string | null
   nextCheckAfter?: string | null
+  lastContentChangeAt?: string | null
   /** ISO-8601 timestamp of when this entry was first created in the catalog DB. */
   createdAt?: string
 }