@collage-dam/mcp-server 0.1.0

package/dist/tools/insights/report-stale-assets.js

@@ -0,0 +1,281 @@
+// ── report_stale_assets (T4, read-only) ──────────────────────────────
+//
+// Read-only distribution-insights tool. Identifies workspace assets that
+// were once distributed (via share links) but have gone dormant — no
+// fresh share link in the requested staleness window, or all covering
+// share links are revoked/expired.
+//
+// Scope discipline:
+//   * `report_stale_assets` is DISTRIBUTION-scoped. Stale *collection*
+//     detection lives in the library audit spec; this tool is only about
+//     individual assets' share-link freshness.
+//   * "Once distributed" matters: an asset that was never shared is not
+//     a finding here — the activation/coverage gap is what
+//     `report_asset_activation` (T2) reports.
+//
+// Staleness signal:
+//   * `last_shared_at` per asset = max(share_link.created_at) across
+//     covering share links.
+//   * An asset is "stale" when `as_of - last_shared_at >= staleness_days`.
+//   * An asset is "all_revoked" when EVERY covering share link is
+//     `status: 'revoked' | 'expired'` — the asset's distribution has
+//     effectively ended even if `last_shared_at` is recent.
+//
+// Type discipline: never uses `any`. Mirrors the T1/T2/T3 factoring so a
+// cache wrapper (T5) can plug in around `reportStaleAssets(...)` without
+// touching the aggregation logic.
+import { z } from 'zod';
+import { createToolError } from '../../conventions/errors.js';
+import { estimateTokens, HARD_CAP_TOKENS } from '../../conventions/response-budget.js';
+// ── Tool description ────────────────────────────────────────────────
+export const REPORT_STALE_ASSETS_DESCRIPTION = 'Read-only report on workspace assets whose distribution has gone ' +
+    'dormant. Identifies assets that were once shared but have no fresh ' +
+    'share link inside the staleness window, plus assets whose every ' +
+    'covering share link is revoked or expired. Returns structured ' +
+    'metrics — totals, top-N oldest-shared assets, and an age-bucket ' +
+    'distribution. Filters: staleness_days (default 90), as_of (defaults ' +
+    'to now), collection_id, top_n. Scope is per-asset distribution only; ' +
+    'stale-collection detection lives in the library audit. No mutation, ' +
+    'no AI prose.';
+// ── Input schema ────────────────────────────────────────────────────
+export const DEFAULT_TOP_N = 10;
+export const MAX_TOP_N = 100;
+export const DEFAULT_STALENESS_DAYS = 90;
+export const MAX_STALENESS_DAYS = 3650; // 10 years
+/**
+ * `as_of` is the reference point for the staleness window. Omit to use
+ * the current time. ISO-8601 date or datetime string; bare dates are
+ * interpreted as end-of-day in UTC (so "everything older than the end of
+ * 2026-04-01 by N days" is the same as "everything older than
+ * 2026-04-01T23:59:59.999Z by N days").
+ */
+export const ReportStaleAssetsInputSchema = z
+    .object({
+    staleness_days: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_STALENESS_DAYS)
+        .default(DEFAULT_STALENESS_DAYS),
+    as_of: z
+        .string()
+        .min(1)
+        .refine((v) => !Number.isNaN(Date.parse(v)), {
+        message: 'as_of must be a valid ISO-8601 date or datetime string',
+    })
+        .optional(),
+    collection_id: z.string().min(1).optional(),
+    top_n: z.number().int().min(1).max(MAX_TOP_N).default(DEFAULT_TOP_N),
+})
+    .strict();
+export class ReportStaleAssetsTool {
+    deps;
+    name = 'report_stale_assets';
+    description = REPORT_STALE_ASSETS_DESCRIPTION;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async run(rawInput = {}) {
+        let parsed;
+        try {
+            parsed = ReportStaleAssetsInputSchema.parse(rawInput);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: createToolError('VALIDATION', err instanceof Error ? err.message : 'invalid input'),
+            };
+        }
+        const enumerated = await this.deps.enumerator.enumerate();
+        if (!enumerated.ok) {
+            return { ok: false, error: enumerated.error };
+        }
+        const report = buildReport(enumerated.rows, enumerated.truncated, parsed);
+        return { ok: true, report };
+    }
+}
+export function buildReportStaleAssetsTool(deps) {
+    return new ReportStaleAssetsTool(deps);
+}
+// ── Aggregation (pure) ──────────────────────────────────────────────
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Build the stale-assets report from a flat list of share-link rows.
+ * Pure function, exported for direct test access.
+ */
+export function buildReport(rows, enumeratorTruncated, input) {
+    // ── Resolve reference timestamp ──
+    const asOfMs = resolveAsOf(input.as_of);
+    const asOfIso = new Date(asOfMs).toISOString();
+    const stalenessThresholdMs = asOfMs - input.staleness_days * MS_PER_DAY;
+    // ── Pre-filter on collection scope only (we DO want pre-as_of rows here) ──
+    // Reason: staleness asks "when was this asset LAST shared?" — we must
+    // include older shares to find that maximum. We only exclude rows
+    // strictly newer than `as_of` (a future-dated row shouldn't make an
+    // asset look fresh from a backward-looking analysis).
+    const matching = rows.filter((row) => {
+        if (input.collection_id !== undefined) {
+            if (row.collection_id !== input.collection_id)
+                return false;
+        }
+        if (row.created_at === null)
+            return false;
+        const createdMs = Date.parse(row.created_at);
+        if (Number.isNaN(createdMs))
+            return false;
+        if (createdMs > asOfMs)
+            return false;
+        return true;
+    });
+    const assets = new Map();
+    for (const row of matching) {
+        if (row.created_at === null)
+            continue;
+        const createdMs = Date.parse(row.created_at);
+        if (Number.isNaN(createdMs))
+            continue;
+        for (const assetId of row.asset_ids) {
+            const existing = assets.get(assetId);
+            const isDead = isRevokedOrExpired(row.status);
+            if (existing === undefined) {
+                assets.set(assetId, {
+                    first_shared_ms: createdMs,
+                    first_shared_iso: row.created_at,
+                    last_shared_ms: createdMs,
+                    last_shared_iso: row.created_at,
+                    share_link_count: 1,
+                    revoked_or_expired_count: isDead ? 1 : 0,
+                    title: row.title,
+                });
+                continue;
+            }
+            existing.share_link_count += 1;
+            if (isDead)
+                existing.revoked_or_expired_count += 1;
+            if (createdMs < existing.first_shared_ms) {
+                existing.first_shared_ms = createdMs;
+                existing.first_shared_iso = row.created_at;
+            }
+            if (createdMs >= existing.last_shared_ms) {
+                existing.last_shared_ms = createdMs;
+                existing.last_shared_iso = row.created_at;
+                // Prefer non-null titles from the most-recent row.
+                if (row.title !== null)
+                    existing.title = row.title;
+            }
+        }
+    }
+    const classified = [];
+    for (const [id, state] of assets.entries()) {
+        const allDead = state.share_link_count > 0 &&
+            state.revoked_or_expired_count === state.share_link_count;
+        const daysSinceLastShare = Math.max(0, Math.floor((asOfMs - state.last_shared_ms) / MS_PER_DAY));
+        const isStaleByAge = state.last_shared_ms <= stalenessThresholdMs;
+        const isStale = isStaleByAge || allDead;
+        classified.push({
+            entry: {
+                id,
+                title: state.title,
+                last_shared_at: state.last_shared_iso,
+                first_shared_at: state.first_shared_iso,
+                days_since_last_share: daysSinceLastShare,
+                share_link_count: state.share_link_count,
+                all_shares_revoked_or_expired: allDead,
+            },
+            is_stale: isStale,
+        });
+    }
+    const staleEntries = classified.filter((c) => c.is_stale).map((c) => c.entry);
+    const allRevokedCount = classified.filter((c) => c.entry.all_shares_revoked_or_expired).length;
+    // ── Summary ──
+    const totalEverShared = assets.size;
+    const summary = {
+        total_ever_shared_assets: totalEverShared,
+        stale_assets: staleEntries.length,
+        fresh_assets: totalEverShared - staleEntries.length,
+        all_revoked_or_expired_assets: allRevokedCount,
+        staleness_rate: totalEverShared > 0 ? staleEntries.length / totalEverShared : null,
+    };
+    // ── Distribution buckets (over stale population) ──
+    const distribution = {
+        month_to_quarter: 0,
+        quarter_to_half_year: 0,
+        half_year_to_year: 0,
+        over_year: 0,
+    };
+    for (const e of staleEntries) {
+        const d = e.days_since_last_share;
+        if (d < 90)
+            distribution.month_to_quarter += 1;
+        else if (d < 180)
+            distribution.quarter_to_half_year += 1;
+        else if (d < 365)
+            distribution.half_year_to_year += 1;
+        else
+            distribution.over_year += 1;
+    }
+    // ── Top N stale (oldest-first; tie-break by share_link_count desc, then id asc) ──
+    const sortedStale = [...staleEntries].sort((a, b) => {
+        if (b.days_since_last_share !== a.days_since_last_share) {
+            return b.days_since_last_share - a.days_since_last_share;
+        }
+        if (b.share_link_count !== a.share_link_count) {
+            return b.share_link_count - a.share_link_count;
+        }
+        return a.id.localeCompare(b.id);
+    });
+    const topStale = sortedStale.slice(0, input.top_n);
+    const initial = {
+        filters: {
+            staleness_days: input.staleness_days,
+            as_of: asOfIso,
+            collection_id: input.collection_id ?? null,
+            top_n: input.top_n,
+        },
+        summary,
+        staleness_distribution: distribution,
+        top_stale_assets: topStale,
+        truncated: enumeratorTruncated,
+    };
+    if (enumeratorTruncated) {
+        initial.truncation_reason =
+            'Share-link enumerator stopped at its internal cap; report reflects a partial dataset.';
+    }
+    return enforceResponseBudget(initial);
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+function isRevokedOrExpired(status) {
+    return status === 'revoked' || status === 'expired';
+}
+function resolveAsOf(rawAsOf) {
+    if (rawAsOf === undefined)
+        return Date.now();
+    // Bare YYYY-MM-DD → end-of-day in UTC, so "stale as of 2026-04-01"
+    // captures activity up through the close of that day.
+    if (/^\d{4}-\d{2}-\d{2}$/.test(rawAsOf)) {
+        return Date.parse(`${rawAsOf}T23:59:59.999Z`);
+    }
+    return Date.parse(rawAsOf);
+}
+// ── Response-budget enforcement ─────────────────────────────────────
+const REDUCED_TOP_LIMIT = 10;
+/**
+ * Aggregate reports tend to be small (totals + top-N + bucket counts).
+ * If the serialised report exceeds {@link HARD_CAP_TOKENS}, trim the
+ * top-asset list and mark `truncated: true`.
+ */
+function enforceResponseBudget(report) {
+    if (estimateTokens(JSON.stringify(report)) <= HARD_CAP_TOKENS) {
+        return report;
+    }
+    const trimmed = {
+        ...report,
+        top_stale_assets: report.top_stale_assets.slice(0, REDUCED_TOP_LIMIT),
+        truncated: true,
+        truncation_reason: report.truncation_reason !== undefined
+            ? `${report.truncation_reason} Additionally, the top-stale-assets list was trimmed to fit the response budget.`
+            : 'Top-stale-assets list was trimmed to fit the response budget.',
+    };
+    return trimmed;
+}
+//# sourceMappingURL=report-stale-assets.js.map

package/dist/tools/insights/report-stale-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-stale-assets.js","sourceRoot":"","sources":["../../../src/tools/insights/report-stale-assets.ts"],"names":[],"mappings":"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"}

package/dist/tools/insights/report-top-assets.d.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+import { type McpToolError } from '../../conventions/errors.js';
+import type { ShareLinkEnumerator, ShareLinkRow } from './analyze-share-links.js';
+export declare const REPORT_TOP_ASSETS_DESCRIPTION: string;
+export declare const DEFAULT_TOP_N = 10;
+export declare const MAX_TOP_N = 100;
+/** Default look-back window when neither `date_from` nor `date_to` is set. */
+export declare const DEFAULT_LOOKBACK_DAYS = 90;
+export declare const SORT_BY_VALUES: readonly ["total_views", "share_link_count", "mean_views_per_share"];
+export type ReportTopAssetsSortBy = (typeof SORT_BY_VALUES)[number];
+/**
+ * `date_from` / `date_to` are inclusive ISO-8601 date or datetime
+ * strings. If only a date is supplied (e.g. `2026-04-14`) it is
+ * interpreted as the start (00:00:00Z) for `date_from` or the end
+ * (23:59:59.999Z) for `date_to`. When BOTH are omitted, the analyzer
+ * defaults to the last {@link DEFAULT_LOOKBACK_DAYS} days — wider than
+ * T2's 30-day default because "top performers" is more interesting over
+ * a quarter than a month.
+ */
+export declare const ReportTopAssetsInputSchema: z.ZodObject<{
+    date_from: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    date_to: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    collection_id: z.ZodOptional<z.ZodString>;
+    created_by_user_id: z.ZodOptional<z.ZodString>;
+    sort_by: z.ZodDefault<z.ZodEnum<["total_views", "share_link_count", "mean_views_per_share"]>>;
+    top_n: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    sort_by: "total_views" | "share_link_count" | "mean_views_per_share";
+    top_n: number;
+    collection_id?: string | undefined;
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+    created_by_user_id?: string | undefined;
+}, {
+    sort_by?: "total_views" | "share_link_count" | "mean_views_per_share" | undefined;
+    collection_id?: string | undefined;
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+    created_by_user_id?: string | undefined;
+    top_n?: number | undefined;
+}>;
+export type ReportTopAssetsInput = z.input<typeof ReportTopAssetsInputSchema>;
+export type ReportTopAssetsInputResolved = z.output<typeof ReportTopAssetsInputSchema>;
+export interface TopAssetEntry {
+    id: string;
+    /** Best-effort title pulled from the most-recent share-link row covering this asset. */
+    title: string | null;
+    /** Sum of view counts across share links covering this asset. */
+    total_views: number;
+    /** Number of share links covering this asset within the matching range. */
+    share_link_count: number;
+    /** Number of distinct user ids that created share links covering this asset. */
+    distinct_creators_count: number;
+    /** Number of distinct collection ids whose shares covered this asset. */
+    distinct_collections_count: number;
+    /** Mean views per share link covering this asset (0 when share_link_count is 0 — guarded for callers iterating without the wrapping list). */
+    mean_views_per_share: number;
+    /** Earliest share-link `created_at` covering this asset (ISO-8601). */
+    first_shared_at: string | null;
+    /** Latest share-link `created_at` covering this asset (ISO-8601). */
+    last_shared_at: string | null;
+}
+export interface TopAssetsTotals {
+    /** Number of distinct assets with any matching share-link activity. */
+    matched_assets: number;
+    /** Sum of view counts across all matching share links. */
+    total_views: number;
+    /** Number of matching share-link rows. */
+    total_shares: number;
+    /** Mean total_views across matched assets (null when matched_assets === 0). */
+    mean_views_per_asset: number | null;
+    /** Median total_views across matched assets (null when matched_assets === 0). */
+    median_views_per_asset: number | null;
+}
+/**
+ * Tier counts using percentile thresholds across the matched-asset
+ * population's total_views distribution.
+ *
+ * Tier boundaries:
+ *   * `high`   — assets at or above the P80 threshold
+ *   * `medium` — assets at or above P50 but below P80
+ *   * `low`    — assets below P50
+ *
+ * `thresholds` exposes the numeric boundary values used so the LLM can
+ * cite "top performers (≥ N views)" in natural language.
+ *
+ * `null` for both thresholds means there were no matched assets to
+ * derive tiers from.
+ */
+export interface PerformanceBuckets {
+    high: number;
+    medium: number;
+    low: number;
+    thresholds: {
+        p80_views: number | null;
+        p50_views: number | null;
+    };
+}
+export interface TopAssetsReport {
+    /** Inputs as resolved (after defaults / filters applied). */
+    filters: {
+        date_from: string | null;
+        date_to: string | null;
+        collection_id: string | null;
+        created_by_user_id: string | null;
+        sort_by: ReportTopAssetsSortBy;
+        top_n: number;
+    };
+    totals: TopAssetsTotals;
+    performance_buckets: PerformanceBuckets;
+    top_assets: TopAssetEntry[];
+    /** True when the share-link enumerator hit its hard cap or the response was trimmed for budget. */
+    truncated: boolean;
+    truncation_reason?: string;
+}
+export interface ReportTopAssetsDeps {
+    enumerator: ShareLinkEnumerator;
+}
+export type ReportTopAssetsOutcome = {
+    ok: true;
+    report: TopAssetsReport;
+} | {
+    ok: false;
+    error: McpToolError;
+};
+export declare class ReportTopAssetsTool {
+    private readonly deps;
+    readonly name = "report_top_assets";
+    readonly description: string;
+    constructor(deps: ReportTopAssetsDeps);
+    run(rawInput?: ReportTopAssetsInput): Promise<ReportTopAssetsOutcome>;
+}
+export declare function buildReportTopAssetsTool(deps: ReportTopAssetsDeps): ReportTopAssetsTool;
+/**
+ * Build the top-assets report from a flat list of share-link rows. Pure
+ * function, exported for direct test access.
+ */
+export declare function buildReport(rows: ReadonlyArray<ShareLinkRow>, enumeratorTruncated: boolean, input: ReportTopAssetsInputResolved): TopAssetsReport;
+//# sourceMappingURL=report-top-assets.d.ts.map

package/dist/tools/insights/report-top-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-top-assets.d.ts","sourceRoot":"","sources":["../../../src/tools/insights/report-top-assets.ts"],"names":[],"mappings":"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"}