@happyvertical/smrt-assets 0.51.39 → 0.52.0

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-assets",
-  "packageVersion": "0.51.39",
+  "packageVersion": "0.52.0",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "956e531d99bbfbc7b5bff0ca3088ff8d212dbcd2b52eba4304938291d9fb264f",
-    "packageJson": "f5d0e8425859e5f7e565853146a183f0c84a5826a640180310535915e2adbe74",
+    "manifest": "e671342445926a793ef28452dc635b43ba6a63f15b11959e5f781cbe167d5f30",
+    "packageJson": "e65913a27bf64dd1be8aa22ccd89be516bb38ce1467cb234cac55ff77c0c2b01",
     "agents": "b20a644cf88ab66f1086b329be02d127f5396026260fbc2c515d5842cfe3d3de"
   },
   "exports": [
@@ -39,7 +39,7 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@types/node": "24.13.6",
-    "svelte": "^5.57.1",
+    "svelte": "^5.57.0",
     "svelte-check": "^4.7.6",
     "tslib": "^2.8.1",
     "typescript": "6.0.3",
@@ -73,7 +73,7 @@
     "versioning"
   ],
   "risks": [
-    "cross-package-refs:2",
+    "cross-package-refs:3",
     "polymorphic-associations:1",
     "sensitive-fields-excluded",
     "sti-inheritance"
@@ -955,6 +955,181 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "AssetTag",
+      "qualifiedName": "@happyvertical/smrt-assets:AssetTag",
+      "collection": "assettags",
+      "tableName": "asset_tags",
+      "packageName": "@happyvertical/smrt-assets",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "tagId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-tags:Tag",
+          "columnType": "UUID"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "assetId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "tagId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-tags:Tag",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "asset_id",
+        "tag_id"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "AssetTagCollection",
+      "qualifiedName": "@happyvertical/smrt-assets:AssetTagCollection",
+      "collection": "assettags",
+      "tableName": "asset_tags",
+      "packageName": "@happyvertical/smrt-assets",
+      "extends": "SmrtJunction",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "attach",
+        "byLeft",
+        "byRight",
+        "detach",
+        "setLinks"
+      ],
+      "methodSignatures": [
+        {
+          "name": "attach",
+          "async": true,
+          "params": [
+            "leftId: string",
+            "rightId: string",
+            "opts?: JunctionAttachOptions"
+          ],
+          "returns": "Promise<TItem>"
+        },
+        {
+          "name": "byLeft",
+          "async": true,
+          "params": [
+            "leftId: string",
+            "opts?: JunctionFilterOptions"
+          ],
+          "returns": "Promise<TItem[]>"
+        },
+        {
+          "name": "byRight",
+          "async": true,
+          "params": [
+            "rightId: string",
+            "opts?: JunctionFilterOptions"
+          ],
+          "returns": "Promise<TItem[]>"
+        },
+        {
+          "name": "detach",
+          "async": true,
+          "params": [
+            "leftId: string",
+            "rightId: string",
+            "opts?: JunctionFilterOptions"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "setLinks",
+          "async": true,
+          "params": [
+            "leftId: string",
+            "rightIds: string[]",
+            "opts?: JunctionAttachOptions"
+          ],
+          "returns": "Promise<void>"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "attach",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-assets:AssetTagCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "byLeft",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-assets:AssetTagCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "byRight",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-assets:AssetTagCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "detach",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-assets:AssetTagCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "setLinks",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-assets:AssetTagCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "SmrtJunction",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "AssetType",
       "qualifiedName": "@happyvertical/smrt-assets:AssetType",
@@ -1365,6 +1540,7 @@
         "getExternalRef",
         "getExternalRefs",
         "getMetadata",
+        "getSlug",
         "getSource",
         "getStatus",
         "getTags",
@@ -1419,6 +1595,11 @@
           "name": "getMetadata",
           "returns": "Record<string, unknown>"
         },
+        {
+          "name": "getSlug",
+          "async": true,
+          "returns": "Promise<string | null | undefined>"
+        },
         {
           "name": "getSource",
           "async": true,
@@ -1443,7 +1624,8 @@
           "name": "hasTag",
           "async": true,
           "params": [
-            "tagSlug: string"
+            "tagSlug: string",
+            "context?: string"
           ],
           "returns": "Promise<boolean>"
         },
@@ -1718,6 +1900,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-assets:Asset"
         },
+        {
+          "kind": "api",
+          "operation": "getSlug",
+          "code": "lifecycle-method",
+          "reason": "`getSlug` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-assets:Asset"
+        },
         {
           "kind": "api",
           "operation": "getSource",
@@ -1806,9 +1995,11 @@
         "getByType",
         "getDerivatives",
         "getLatestVersion",
+        "getTagsForAssets",
         "listVersions",
         "removeTag",
-        "rollbackToVersion"
+        "rollbackToVersion",
+        "setTags"
       ],
       "methodSignatures": [
         {
@@ -1816,9 +2007,10 @@
           "async": true,
           "params": [
             "assetId: string",
-            "tagSlug: string"
+            "tag: string",
+            "options?: AssetTagInput"
           ],
-          "returns": "Promise<void>"
+          "returns": "Promise<Tag>"
         },
         {
           "name": "createNewVersion",
@@ -1887,7 +2079,8 @@
           "name": "getByTag",
           "async": true,
           "params": [
-            "tagSlug: string"
+            "tag: string",
+            "options?: Pick<AssetTagInput, 'context'>"
           ],
           "returns": "Promise<Asset[]>"
         },
@@ -1915,6 +2108,14 @@
           ],
           "returns": "Promise<Asset | null>"
         },
+        {
+          "name": "getTagsForAssets",
+          "async": true,
+          "params": [
+            "assetIds: string[]"
+          ],
+          "returns": "Promise<Map<string, Tag[]>>"
+        },
         {
           "name": "listVersions",
           "async": true,
@@ -1928,7 +2129,8 @@
           "async": true,
           "params": [
             "assetId: string",
-            "tagSlug: string"
+            "tag: string",
+            "options?: Pick<AssetTagInput, 'context'>"
           ],
           "returns": "Promise<void>"
         },
@@ -1940,6 +2142,16 @@
             "targetVersion: number"
           ],
           "returns": "Promise<Asset>"
+        },
+        {
+          "name": "setTags",
+          "async": true,
+          "params": [
+            "assetId: string",
+            "tags: string[]",
+            "options?: Pick<AssetTagInput, 'context'>"
+          ],
+          "returns": "Promise<Tag[]>"
         }
       ],
       "surfaces": [
@@ -1983,6 +2195,22 @@
           "path": "/assets/removeTag",
           "method": "POST"
         },
+        {
+          "kind": "api",
+          "name": "assets.setTags",
+          "operation": "setTags",
+          "objectName": "@happyvertical/smrt-assets:AssetCollection",
+          "path": "/assets/setTags",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "assets.getTagsForAssets",
+          "operation": "getTagsForAssets",
+          "objectName": "@happyvertical/smrt-assets:AssetCollection",
+          "path": "/assets/getTagsForAssets",
+          "method": "POST"
+        },
         {
           "kind": "api",
           "name": "assets.getByTag",
@@ -2093,6 +2321,18 @@
           "operation": "removeTag",
           "objectName": "@happyvertical/smrt-assets:AssetCollection"
         },
+        {
+          "kind": "cli",
+          "name": "assetcollection_setTags",
+          "operation": "setTags",
+          "objectName": "@happyvertical/smrt-assets:AssetCollection"
+        },
+        {
+          "kind": "cli",
+          "name": "assetcollection_getTagsForAssets",
+          "operation": "getTagsForAssets",
+          "objectName": "@happyvertical/smrt-assets:AssetCollection"
+        },
         {
           "kind": "cli",
           "name": "assetcollection_getByTag",
@@ -2189,6 +2429,18 @@
           "operation": "removeTag",
           "objectName": "@happyvertical/smrt-assets:AssetCollection"
         },
+        {
+          "kind": "mcp",
+          "name": "assetcollection_settags",
+          "operation": "setTags",
+          "objectName": "@happyvertical/smrt-assets:AssetCollection"
+        },
+        {
+          "kind": "mcp",
+          "name": "assetcollection_gettagsforassets",
+          "operation": "getTagsForAssets",
+          "objectName": "@happyvertical/smrt-assets:AssetCollection"
+        },
         {
           "kind": "mcp",
           "name": "assetcollection_getbytag",
@@ -3566,6 +3818,22 @@
       "path": "/assets/removeTag",
       "method": "POST"
     },
+    {
+      "kind": "api",
+      "name": "assets.setTags",
+      "operation": "setTags",
+      "objectName": "@happyvertical/smrt-assets:AssetCollection",
+      "path": "/assets/setTags",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "assets.getTagsForAssets",
+      "operation": "getTagsForAssets",
+      "objectName": "@happyvertical/smrt-assets:AssetCollection",
+      "path": "/assets/getTagsForAssets",
+      "method": "POST"
+    },
     {
       "kind": "api",
       "name": "assets.getByTag",
@@ -3676,6 +3944,18 @@
       "operation": "removeTag",
       "objectName": "@happyvertical/smrt-assets:AssetCollection"
     },
+    {
+      "kind": "cli",
+      "name": "assetcollection_setTags",
+      "operation": "setTags",
+      "objectName": "@happyvertical/smrt-assets:AssetCollection"
+    },
+    {
+      "kind": "cli",
+      "name": "assetcollection_getTagsForAssets",
+      "operation": "getTagsForAssets",
+      "objectName": "@happyvertical/smrt-assets:AssetCollection"
+    },
     {
       "kind": "cli",
       "name": "assetcollection_getByTag",
@@ -3772,6 +4052,18 @@
       "operation": "removeTag",
       "objectName": "@happyvertical/smrt-assets:AssetCollection"
     },
+    {
+      "kind": "mcp",
+      "name": "assetcollection_settags",
+      "operation": "setTags",
+      "objectName": "@happyvertical/smrt-assets:AssetCollection"
+    },
+    {
+      "kind": "mcp",
+      "name": "assetcollection_gettagsforassets",
+      "operation": "getTagsForAssets",
+      "objectName": "@happyvertical/smrt-assets:AssetCollection"
+    },
     {
       "kind": "mcp",
       "name": "assetcollection_getbytag",
@@ -4041,12 +4333,12 @@
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 5,
-    "crossPackageRefFields": 2,
-    "junctionCollections": 1,
+    "foreignKeyFields": 6,
+    "crossPackageRefFields": 3,
+    "junctionCollections": 2,
     "hierarchicalObjects": 1,
     "polymorphicAssociations": 1,
-    "uuidColumns": 32
+    "uuidColumns": 40
   },
   "agentDoc": "# @happyvertical/smrt-assets\n\nProvider-agnostic asset management with versioning, type classification, and generic/provenance associations.\n\n## Models\n\n- **Asset** (STI base): versioning via `primaryVersionId` chain + `version` number. `ownerProfileId`, `typeSlug`, `statusSlug`, `mimeType`, `sourceUri`. Derivation chain via `sourceAssetId` (R3-D — was `parentId` before the rename; column `source_asset_id`).\n- **AssetType** / **AssetStatus**: lookup tables for classification and lifecycle.\n- **AssetMetafield**: custom metadata field definitions with JSON validation rules.\n- **Folder**: hierarchical container for assets. Own `SmrtHierarchical` model with its own `folders` table (R3-D — was an STI subclass of Asset before). `Asset.folderId` points to the folder.\n- **AssetAssociation**: generic/provenance polymorphic join — `assetId` + `metaType` + `metaId` + `role` + `sortOrder`. Use it when a relationship is not owned by a base/domain model join table like `content_assets`, `profile_assets`, `event_assets`, `place_assets`, or `product_assets`.\n\n## Key Patterns\n\n- **Versioning**: `createNewVersion()` increments version, chains via `primaryVersionId`. `findVersions()` to retrieve history.\n- **Tag integration**: `addTag()`/`removeTag()` use raw `db.upsert()` on `asset_tags` join table (not a SMRT model).\n- **AssetStore**: abstraction for provider-agnostic file I/O (S3, local, etc.).\n- **Ownership rule**: base/domain-owned asset relationships should live on noun join tables such as `content_assets`, `profile_assets`, `event_assets`, `place_assets`, and `product_assets`; keep `AssetAssociation` for generic/provenance links like image derivation.\n\n## Runtime surface\n\nApps and agents should depend on the public **asset runtime** rather than hand-wiring a collection + store per-package (#1128).\n\n- `createAssetRuntime({ db, storage })` → `AssetRuntime` bundling `AssetCollection`, `AssetAssociationCollection`, and an initialized `AssetStore`.\n- `AssetRuntime.storeSourceAsset(name, data, opts)` — create a new source asset (record + bytes).\n- `AssetRuntime.storeDerivedAsset(source, name, data, opts)` — create a derivative with `sourceAssetId` set and (by default) a provenance `AssetAssociation` under a chosen role.\n- `AssetRuntime.linkDerivation(source, derivative, { role })` — record provenance without touching bytes.\n- `AssetRuntime.setExtractionStatus(asset, status, { error?, extractedAt? })` — write canonical extraction metadata into the asset's description JSON sidecar. Non-destructive: if `description` is free-form prose or non-object JSON, the original value is preserved under the reserved `text` key instead of being overwritten. Existing JSON objects are merged into.\n\nAgents that need asset I/O should accept an `AssetRuntimeLike` in their options rather than asking callers to pass a store + collection separately.\n\n## Serving contract\n\n- `serveAsset({ runtime, asset, tenantId?, disposition?, canAccess?, headers?, remoteMode? })` → standard Web `Response`.\n  - `404` when the id doesn't resolve; `403` when the tenant mismatches or `canAccess` denies; `302` when `remoteMode: 'redirect'` and the asset's `sourceUri` is `http(s)`; `502` when `remoteMode: 'proxy'` and the origin fetch fails; `500` on store read errors or unexpected failures; `200` otherwise with `Content-Type`, `Content-Length`, and `Content-Disposition` set.\n  - Assets whose `sourceUri` is `http(s)` are supported via `remoteMode`: `'proxy'` (default, fetch and return bytes), `'redirect'` (302 to the origin), or `'error'` (treat as misconfiguration). Pass `fetchImpl` to swap the fetch client.\n  - `Content-Disposition` uses an ASCII-safe quoted `filename` fallback and retains the Unicode download name in UTF-8 `filename*` ([RFC 6266](https://www.rfc-editor.org/rfc/rfc6266#section-4.3), [RFC 8187](https://www.rfc-editor.org/rfc/rfc8187#section-3.2.1)). Both names strip C0/DEL/C1 controls and replace `\"` / `\\` / `/` to prevent header injection; isolated UTF-16 surrogates become U+FFFD before encoding, while valid pairs are preserved.\n  - The 500 body is a generic `'Internal error serving asset'`; the underlying error is logged via `console.error` so operators can debug without leaking paths/bucket names to clients.\n  - Works in SvelteKit `+server.ts` endpoints, Hono, and any runtime with a global `Response` (Node 18+). Pass `responseCtor` for older runtimes.\n- `resolveAssetForServing(options)` → `{ asset, data, contentType, filename, size }` when callers want to render their own framework response. Throws `AssetServeError(status)` on the same failure modes.\n\n## Source/derived vocabulary\n\nThe following roles are exported as `ASSET_ROLES` and should be preferred over ad-hoc strings when apps want cross-package tooling (serving, UI pickers) to agree on meaning:\n\n| Role | Use |\n|------|-----|\n| `source_document` | original upstream document (agenda PDF, minutes) |\n| `document_image` | page/extracted image derived from a source document |\n| `thumbnail` | preview rendition of another asset |\n| `proof` | non-canonical evidence asset backing a fact |\n| `derivation_source` | \"came from\" link on generated media |\n| `attachment` | generic owner-join link |\n| `hero` | primary/featured asset on an owner |\n\nCanonical metadata keys are exported as `ASSET_METADATA_KEYS`: `extractionStatus`, `extractionError`, `extractedAt`, `sourceUrl`, `sourceHash`, `pageNumber`. Extraction status values live in `ASSET_EXTRACTION_STATUS` (`pending | running | succeeded | failed`).\n\n## UI Registry\n\nThe `./ui` subpath exports `ASSETS_MODULE_META` and `ASSETS_UI_SLOTS` so registry-driven hosts (smrt-chat, dynamic admin shells) can discover the package's Svelte components without a hard import.\n\n```ts\nimport { ASSETS_MODULE_META, ASSETS_UI_SLOTS } from '@happyvertical/smrt-assets/ui';\nimport '@happyvertical/smrt-assets/svelte'; // side-effect: ModuleUIRegistry.register(...)\nimport { ModuleUIRegistry } from '@happyvertical/smrt-ui/registry';\n\nconst AssetManager = ModuleUIRegistry.get('@happyvertical/smrt-assets', 'asset-manager');\n```\n\nRegistered slots: `asset-manager` (admin), `asset-grid` / `asset-list` (list), `asset-detail` (detail), `asset-toolbar` / `asset-action-bar` (action), `asset-create-modal` (form). Slot IDs are stable contracts — host apps reference them by string.\n\n## Gotchas\n\n- **Files SDK is a lazy boundary (#1979)**: `AssetStore` loads `@happyvertical/files` through `src/files-runtime.ts` (bundler-invisible), because smrt-assets is reachable from provider-neutral consumer graphs via profiles. Node/tsx/vite-dev runtimes resolve it on first file operation; fully-bundled deployments import `@happyvertical/smrt-assets/filesystem` at startup. Never import the files SDK statically from modules reachable from `src/index.ts`.\n- **Version history manual**: `findVersions()` chaining required — no ORM shortcut\n- **Tag management uses raw SQL**: `asset_tags` is a join table, not an SMRT model\n- **Folder tree traversal**: via `SmrtHierarchical` (`getParent`/`getChildren`/`getAncestors`/`getDescendants`/`getHierarchy`/`moveTo`); `FolderCollection.getTree(rootId?)` and `getPath(folderId)` wrap these for convenience\n- **AssetAssociation polymorphic FK**: requires manual `metaType` string matching\n- **Optional tenancy**: assets can be global (tenantId=null) or tenant-scoped\n"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-assets",
-  "version": "0.51.39",
+  "version": "0.52.0",
   "smrtJsdoc": "strict",
   "description": "Asset management system with versioning, metadata, and AI-powered operations for SMRT framework",
   "type": "module",
@@ -43,19 +43,19 @@
     }
   },
   "dependencies": {
-    "@happyvertical/ai": "^0.96.0",
-    "@happyvertical/files": "^0.96.0",
-    "@happyvertical/logger": "^0.96.0",
-    "@happyvertical/smrt-core": "0.51.39",
-    "@happyvertical/smrt-tags": "0.51.39",
-    "@happyvertical/smrt-tenancy": "0.51.39",
-    "@happyvertical/smrt-types": "0.51.39",
-    "@happyvertical/smrt-ui": "0.51.39",
-    "@happyvertical/sql": "^0.96.0",
-    "@happyvertical/utils": "^0.96.0"
+    "@happyvertical/ai": "^0.96.1",
+    "@happyvertical/files": "^0.96.1",
+    "@happyvertical/logger": "^0.96.1",
+    "@happyvertical/smrt-core": "0.52.0",
+    "@happyvertical/smrt-tags": "0.52.0",
+    "@happyvertical/smrt-tenancy": "0.52.0",
+    "@happyvertical/smrt-types": "0.52.0",
+    "@happyvertical/smrt-ui": "0.52.0",
+    "@happyvertical/sql": "^0.96.1",
+    "@happyvertical/utils": "^0.96.1"
   },
   "peerDependencies": {
-    "svelte": "^5.57.1"
+    "svelte": "^5.57.0"
   },
   "peerDependenciesMeta": {
     "svelte": {
@@ -63,8 +63,8 @@
     }
   },
   "devDependencies": {
-    "@happyvertical/smrt-playground": "0.51.39",
-    "@happyvertical/smrt-vitest": "0.51.39",
+    "@happyvertical/smrt-playground": "0.52.0",
+    "@happyvertical/smrt-vitest": "0.52.0",
     "@sveltejs/adapter-auto": "^7.0.1",
     "@sveltejs/kit": "2.69.1",
     "@sveltejs/package": "^2.5.8",