feat(assets): add 'used_by' attribute to assets for tracking workspace workflows

Author: dkackman

docs/SERVER.md

@@ -575,7 +575,11 @@ The editor's forms come from these; they are just as usable from scripts:
   delete can actually reach is the one with `writable: true`. `shadowed`
   lists the entries a nearer library hides: same shape as an `assets` entry
   but without `url` (that URL would serve the shadowing file, not this one),
-  plus `shadowed_by` naming the origin that won. The workflow and prompt
+  plus `shadowed_by` naming the origin that won. An `assets` entry carries
+  `used_by` when any of the workspace's own (writable) workflows names it in
+  an `asset:` string, variable defaults included - a reference a run passes
+  as an argument is not seen; the web UI shows a workspace only the shared
+  assets its workflows use. The workflow and prompt
   listings carry the same `libraries` and `shadowed` (`[{name, origin,
   shadowed_by}]`); a filter narrows `shadowed` with the entries. Upload, keep
   and delete answer 409 `This workspace has no asset library` when there is

dw/server/api_models.py

@@ -869,6 +869,10 @@ class AssetFile(ApiModel):
     writable: bool
     url: str
     absolute_url: str = sometimes()
+    used_by: list[str] = sometimes(
+        "This workspace's own workflows that name it in an `asset:` reference, "
+        "when any do"
+    )
 
 
 class ShadowedAsset(ApiModel):

dw/server/app.py

@@ -155,6 +155,8 @@ def _store_serving(
     # One index per distinct listing, per app (see deps.ceiling_index)
     state.ceiling_indexes = {}
     state.catalog_listings = {}
+    # Which workspace workflows name each asset (see deps.asset_users)
+    state.asset_users = {}
 
 
 def _mount_mcp(app, mcp_asgi):

dw/server/deps.py

@@ -12,7 +12,9 @@
 
 from fastapi import HTTPException, Request
 
-from ..security import SecurityError
+from .. import references
+from ..realize import strings_with_prefix
+from ..security import SecurityError, validate_asset_reference
 from ..vram_inheritance import build_index, inherited_differences, template_identity
 from .observed_cost import declared_drivers
 from ..library import ASSETS_KIND, LORAS_KIND, PROMPTS_KIND, library_path
@@ -171,6 +173,36 @@ def ceiling_index(state, ws):
     return index
 
 
+def asset_users(state, ws):
+    """Which of this workspace's own workflows name each asset: `{asset name:
+    [workflow name, ...]}`, over the writable libraries of its search path -
+    the population the Workflows page lists, not the read-only examples.
+
+    Read off every `asset:` string a definition holds, variable defaults
+    included, the way an export collects them (`dw/server/exports.py`). A
+    reference the definition builds at run time, or one a run passes as an
+    argument, is not seen. Cached per catalog listing, as `ceiling_index` is.
+    """
+    catalog = _catalog_listing(state, ws)
+    cached = state.asset_users.get(ws.name)
+    if cached and cached[0] is catalog:
+        return cached[1]
+    users = {}
+    for name, definition, writable in catalog:
+        if not writable:
+            continue
+        for reference in strings_with_prefix(definition, references.ASSET):
+            try:
+                asset = validate_asset_reference(
+                    references.ref_name(references.ASSET, reference).strip()
+                )
+            except SecurityError:
+                continue
+            users.setdefault(asset, []).append(name)
+    state.asset_users[ws.name] = (catalog, users)
+    return users
+
+
 def _pipeline_steps(definition):
     return sum(
         1

dw/server/routes/assets.py

@@ -38,6 +38,7 @@
 from ...workspace import Workspace, forget_workspace_usage
 from ..deps import (
     asset_library_missing,
+    asset_users,
     selected_workspace,
     writable_asset_directory,
 )
@@ -219,6 +220,10 @@ def list_assets(
     `prefix` keeps the assets (and shadowed names) whose name starts with
     it; `limit` then keeps the newest that many. `total` is what matched
     before the cut, so a caller can tell a bounded answer from a complete one.
+
+    `used_by` names the workspace's own workflows that reference an asset
+    (`asset_users`) - what lets a workspace show the shared assets it
+    actually uses rather than the whole shared library.
     """
     library = workspace_asset_library(request.app.state, ws)
     if not library.roots():
@@ -267,6 +272,7 @@ def summary(name, root):
             "writable": root.writable,
         }
 
+    users = asset_users(request.app.state, ws)
     assets = []
     for name, root in winners.items():
         asset_path = f"/inputs/{quote(name)}"
@@ -276,6 +282,8 @@ def summary(name, root):
         absolute_url = absolute_served_url(asset_path, ws)
         if absolute_url is not None:
             asset_entry["absolute_url"] = absolute_url
+        if name in users:
+            asset_entry["used_by"] = users[name]
         assets.append(asset_entry)
     assets.sort(key=lambda entry: entry["mtime"], reverse=True)
     if prefix:

tests/test_server_library_path.py

@@ -287,6 +287,58 @@ def test_limit_and_prefix_cut_server_side_and_total_counts_the_match(self, serve
         assert only["shadowed"] == []
 
 
+class TestAnAssetSaysWhichWorkspaceWorkflowsUseIt:
+    """`used_by` names the workspace's own workflows that reference an asset,
+    so the workspace's Assets page can show the shared assets it uses
+    without listing the whole shared library. An example's references do
+    not count: an example is not the workspace's."""
+
+    @pytest.fixture
+    def server(self, make_server):
+        server = make_server()
+        for name in ("cast/priya.png", "unused.png", "example-only.png"):
+            path = os.path.join(server.workspace.common_assets, name)
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "wb") as file:
+                file.write(b"x")
+        for directory, name, reference in (
+            (server.workspace.workflows, "portrait", "asset:cast/priya.png"),
+            (server.workspace.workflows, "sequel", "asset:cast/priya.png"),
+            (str(server.checkout / "workflows"), "example", "asset:example-only.png"),
+        ):
+            workflow = valid_workflow()
+            workflow["variables"]["image"] = reference
+            with open(os.path.join(directory, f"{name}.json"), "w") as file:
+                json.dump(workflow, file)
+        return server
+
+    def used_by(self, server):
+        assets = server.client.get("/api/assets").json()["assets"]
+        return {a["name"]: a.get("used_by") for a in assets}
+
+    def test_a_referenced_asset_names_its_workflows(self, server):
+        assert self.used_by(server)["cast/priya.png"] == ["portrait", "sequel"]
+
+    def test_an_unreferenced_asset_carries_no_used_by(self, server):
+        assert self.used_by(server)["unused.png"] is None
+
+    def test_an_examples_reference_does_not_count(self, server):
+        assert self.used_by(server)["example-only.png"] is None
+
+    def test_a_saved_edit_is_seen_on_the_next_listing(self, server):
+        workflow = valid_workflow()
+        workflow["variables"]["image"] = "asset:unused.png"
+        path = os.path.join(server.workspace.workflows, "portrait.json")
+        with open(path, "w") as file:
+            json.dump(workflow, file)
+        # A later mtime, so the catalog cache sees the change
+        stat = os.stat(path)
+        os.utime(path, (stat.st_atime, stat.st_mtime + 5))
+        used = self.used_by(server)
+        assert used["unused.png"] == ["portrait"]
+        assert used["cast/priya.png"] == ["sequel"]
+
+
 class TestWorkspaceRegistryNamesTheServersPrompts:
     def test_a_named_workspace_reports_the_servers_prompt_dir(
         self, make_server, tmp_path

ui/src/lib/assets/AssetDetail.svelte

@@ -3,6 +3,8 @@
   import CopyButton from '../CopyButton.svelte'
   import type { AssetFile } from '../types'
   import { formatBytes, formatMtime } from '../format'
+  import { wsHref } from '../routes'
+  import { workspace } from '../workspace.svelte'
 
   // The popout for the one asset picked: its reference to copy, the file,
   // and a delete unless a read-only library brought it
@@ -61,6 +63,15 @@
       aria-label="close details"><X size={14} /></button
     >
   </div>
+  {#if asset.used_by?.length}
+    <p class="usedby muted">
+      used by
+      {#each asset.used_by as name, i (name)}{i ? ', ' : ''}<a
+          href={wsHref(workspace.current, 'workflows', ...name.split('/'))}
+          >{name}</a
+        >{/each}
+    </p>
+  {/if}
   <div class="body">
     {#if asset.kind === 'image'}
       <img src={asset.url} alt={asset.name} />
@@ -76,6 +87,10 @@
 </div>
 
 <style>
+  .usedby {
+    margin: 0 0 var(--space-2);
+    font-size: var(--t-sm);
+  }
   /* The gallery's popout: it rides the bottom of the viewport while the
      grid scrolls behind it. Sitting at the end of the document instead
      would put it off screen for any click above the fold */

ui/src/lib/assets/LibraryRow.svelte

@@ -37,10 +37,12 @@
     <span class="muted" title="read-only: this server cannot write to it"
       >read-only</span
     >
-  {:else if section.origin === 'common'}
+  {:else if section.origin === 'common' && shared}
+    <!-- Only on the Shared assets page: a workspace's page shows just the
+         shared assets its workflows use, so an upload there would vanish
+         from the section it was made in -->
     <button
       class="withicon"
-      class:quiet={!shared}
       onclick={() => onupload('shared')}
       disabled={busy}
       title="lands in the shared library - visible from every workspace under this root and cannot be moved afterwards"

ui/src/lib/generated/api-schema.ts

@@ -25,6 +25,10 @@ export interface paths {
          *     `prefix` keeps the assets (and shadowed names) whose name starts with
          *     it; `limit` then keeps the newest that many. `total` is what matched
          *     before the cut, so a caller can tell a bounded answer from a complete one.
+         *
+         *     `used_by` names the workspace's own workflows that reference an asset
+         *     (`asset_users`) - what lets a workspace show the shared assets it
+         *     actually uses rather than the whole shared library.
          */
         get: operations["list_assets_api_assets_get"];
         put?: never;
@@ -1802,6 +1806,11 @@ export interface components {
             size: number;
             /** Url */
             url: string;
+            /**
+             * Used By
+             * @description This workspace's own workflows that name it in an `asset:` reference, when any do
+             */
+            used_by?: string[];
             /** Writable */
             writable: boolean;
         };

ui/src/lib/generated/openapi.json

@@ -159,6 +159,14 @@
             "title": "Url",
             "type": "string"
           },
+          "used_by": {
+            "description": "This workspace's own workflows that name it in an `asset:` reference, when any do",
+            "items": {
+              "type": "string"
+            },
+            "title": "Used By",
+            "type": "array"
+          },
           "writable": {
             "title": "Writable",
             "type": "boolean"
@@ -4696,7 +4704,7 @@
   "paths": {
     "/api/assets": {
       "get": {
-        "description": "The asset library: the input media an 'asset:' reference names.\n\nReported by reference rather than by path - 'asset:uploads/x.png' is\nwhat a workflow argument carries, and a client that only ever sees\nreferences cannot accidentally write a path that means something\nelse on another machine. Empty, not an error, on a server with no\nlibrary configured: nothing is wrong, there is just nowhere for an\nasset to be.\n\n`prefix` keeps the assets (and shadowed names) whose name starts with\nit; `limit` then keeps the newest that many. `total` is what matched\nbefore the cut, so a caller can tell a bounded answer from a complete one.",
+        "description": "The asset library: the input media an 'asset:' reference names.\n\nReported by reference rather than by path - 'asset:uploads/x.png' is\nwhat a workflow argument carries, and a client that only ever sees\nreferences cannot accidentally write a path that means something\nelse on another machine. Empty, not an error, on a server with no\nlibrary configured: nothing is wrong, there is just nowhere for an\nasset to be.\n\n`prefix` keeps the assets (and shadowed names) whose name starts with\nit; `limit` then keeps the newest that many. `total` is what matched\nbefore the cut, so a caller can tell a bounded answer from a complete one.\n\n`used_by` names the workspace's own workflows that reference an asset\n(`asset_users`) - what lets a workspace show the shared assets it\nactually uses rather than the whole shared library.",
         "operationId": "list_assets_api_assets_get",
         "parameters": [
           {