@phosphorco/bb-cross-references 0.0.0-stage → 0.1.1

package/dist/references.css

@@ -0,0 +1,66 @@
+
+.bb-reference-links__references { display: grid; gap: 10px; margin-top: 10px; padding: 12px; border: 1px solid var(--border); border-radius: 9px; background: var(--card); color: var(--card-foreground); }
+
+.bb-reference-links__references > header { display: flex; align-items: start; justify-content: space-between; gap: 12px; }
+
+.bb-reference-links__references h2 { font-size: 12px; font-weight: 650; }
+
+.bb-reference-links__references header p, .bb-reference-links__reference-help, .bb-reference-links__reference-status, .bb-reference-links__reference-empty, .bb-reference-links__reference-error { color: var(--muted-foreground); font-size: 10px; }
+
+.bb-reference-links__references header p { margin-top: 3px; max-width: 620px; }
+
+.bb-reference-links__reference-count { min-width: 1.75rem; padding: 3px 6px; border-radius: 999px; color: var(--primary-foreground); background: var(--primary); font-size: 10px; font-variant-numeric: tabular-nums; text-align: center; }
+
+.bb-reference-links__reference-status { margin: 0; }
+
+.bb-reference-links__reference-status--pending { color: var(--primary); }
+
+.bb-reference-links__reference-status--degraded, .bb-reference-links__reference-status--blocked, .bb-reference-links__reference-error { color: var(--destructive); }
+
+.bb-reference-links__reference-empty { margin: 0; padding: 8px; border-radius: 6px; background: color-mix(in srgb, var(--muted) 36%, transparent); }
+
+.bb-reference-links__reference-list, .bb-reference-links__reference-search-results { display: grid; gap: 6px; margin: 0; padding: 0; list-style: none; }
+
+.bb-reference-links__reference-list li, .bb-reference-links__reference-search-results li { display: flex; align-items: center; justify-content: space-between; gap: 10px; min-width: 0; padding: 7px 8px; border-radius: 6px; background: color-mix(in srgb, var(--muted) 36%, transparent); }
+
+.bb-reference-links__reference-list li > span, .bb-reference-links__reference-search-results li > span { display: grid; min-width: 0; gap: 2px; }
+
+.bb-reference-links__reference-list small, .bb-reference-links__reference-search-results small { overflow: hidden; color: var(--muted-foreground); font-size: 10px; text-overflow: ellipsis; white-space: nowrap; }
+
+.bb-reference-links__reference-link { min-width: 0; overflow: hidden; color: var(--primary); font-size: 12px; font-weight: 600; text-overflow: ellipsis; white-space: nowrap; }
+
+.bb-reference-links__reference-picker { display: grid; gap: 4px; padding-top: 2px; }
+
+.bb-reference-links__reference-picker > label { color: var(--foreground); font-size: 11px; }
+
+.bb-reference-links__reference-picker input { width: 100%; min-height: 32px; padding: 0 9px; border: 1px solid var(--input); border-radius: 7px; color: var(--foreground); background: var(--background); font: inherit; }
+
+.bb-reference-links__reference-picker input:focus-visible, .bb-reference-links__reference-list button:focus-visible, .bb-reference-links__reference-search-results button:focus-visible, .bb-reference-links__reference-external button:focus-visible, .bb-reference-links__reference-retry:focus-visible, .bb-reference-links__reference-link:focus-visible { outline: 2px solid var(--ring); outline-offset: 2px; }
+
+.bb-reference-links__reference-help { margin: 0; }
+
+.bb-reference-links__reference-error { margin: 0; overflow-wrap: anywhere; }
+
+.bb-reference-links__reference-search-results { max-height: 230px; overflow-y: auto; overscroll-behavior: contain; }
+
+.bb-reference-links__reference-search-results strong { min-width: 0; overflow: hidden; font-size: 11px; text-overflow: ellipsis; white-space: nowrap; }
+
+.bb-reference-links__reference-list button, .bb-reference-links__reference-search-results button, .bb-reference-links__reference-external button, .bb-reference-links__reference-retry { flex: 0 0 auto; min-height: 28px; padding: 4px 8px; border: 1px solid var(--border); border-radius: 6px; color: var(--foreground); background: var(--background); font: inherit; font-size: 10px; cursor: pointer; }
+
+.bb-reference-links__reference-search-results button:not(:disabled):hover, .bb-reference-links__reference-list button:not(:disabled):hover, .bb-reference-links__reference-external button:not(:disabled):hover, .bb-reference-links__reference-retry:not(:disabled):hover { background: var(--accent); color: var(--accent-foreground); }
+
+.bb-reference-links__reference-list button:disabled, .bb-reference-links__reference-search-results button:disabled, .bb-reference-links__reference-external button:disabled, .bb-reference-links__reference-retry:disabled { cursor: default; opacity: .58; }
+
+.bb-reference-links__reference-add { color: var(--primary); }
+
+.bb-reference-links__reference-remove { color: var(--destructive) !important; }
+
+.bb-reference-links__reference-external { display: grid; gap: 6px; padding: 8px; border-radius: 6px; background: color-mix(in srgb, var(--muted) 36%, transparent); }
+
+.bb-reference-links__reference-external > span { display: grid; min-width: 0; gap: 2px; }
+
+.bb-reference-links__reference-external strong, .bb-reference-links__reference-external > label { font-size: 11px; }
+
+.bb-reference-links__reference-external small { overflow: hidden; color: var(--muted-foreground); font-size: 10px; text-overflow: ellipsis; white-space: nowrap; }
+
+.bb-reference-links__reference-external > div { display: flex; align-items: center; gap: 6px; }

package/dist/testing.js

@@ -0,0 +1,48 @@
+// src/testing.ts
+import { canonicalizeIdentity, normalizeProjectionCommand, resourceIdentityOf } from "./index.js";
+import { createCrossReferencesClient } from "./bb.js";
+async function runCrossReferencesConformance(options) {
+  const command = normalizeProjectionCommand(options.command);
+  if (command.tombstone || command.targets.length === 0)
+    throw new Error("Conformance requires an active projection with targets.");
+  const client = createCrossReferencesClient(options.sdk, options.pluginId);
+  const checks = [];
+  await client.describe();
+  checks.push("describe-or-legacy-v1");
+  const applied = await client.applyProjection(options.command);
+  if (!["applied", "duplicate", "equal"].includes(applied.outcome) || applied.currentRevision !== command.revision || applied.currentDigest !== command.payloadDigest) {
+    throw new Error("applyProjection did not accept the fixture revision and digest.");
+  }
+  checks.push("apply-acceptance");
+  const duplicate = await client.applyProjection(options.command);
+  if (duplicate.outcome !== "duplicate" || duplicate.currentRevision !== command.revision || duplicate.currentDigest !== command.payloadDigest)
+    throw new Error("Identical mutation was not an exact duplicate.");
+  checks.push("duplicate-acceptance");
+  const source = resourceIdentityOf(command.source);
+  const { projection } = await client.getProjection({ producerPluginId: command.producerPluginId, source });
+  if (projection === null || projection.revision !== command.revision || projection.mutationId !== command.mutationId || projection.payloadDigest !== command.payloadDigest || projection.tombstone || projection.producerPluginId !== command.producerPluginId) {
+    throw new Error("getProjection did not preserve the accepted fixture.");
+  }
+  const readCommand = normalizeProjectionCommand({ ...projection, protocolVersion: 1, expectedRevision: command.expectedRevision });
+  if (readCommand.payloadJson !== command.payloadJson)
+    throw new Error("getProjection changed the accepted source, targets or presentation.");
+  checks.push("get-acceptance");
+  for (const target of command.targets) {
+    let cursor;
+    let found = false;
+    for (let page = 0;page < 10; page += 1) {
+      const backlinks = await client.listBacklinks({ target: resourceIdentityOf(target), pageSize: 100, ...cursor === undefined ? {} : { cursor } });
+      found = backlinks.rows.some((row) => row.producerPluginId === command.producerPluginId && row.revision === command.revision && canonicalizeIdentity({ provider: row.source.provider, keys: row.source.keys }).canonicalIdentityJson === command.source.canonicalIdentityJson);
+      if (found || backlinks.nextCursor === null)
+        break;
+      cursor = backlinks.nextCursor;
+    }
+    if (!found)
+      throw new Error("listBacklinks did not include the accepted source and producer.");
+  }
+  checks.push("backlinks-acceptance");
+  return { level: "source-conformance", pluginId: client.pluginId, checks };
+}
+export {
+  runCrossReferencesConformance
+};

package/dist/types/bb.d.ts

@@ -0,0 +1,29 @@
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+import type { PluginBrowserBbSdk } from "@get-bb/plugin-sdk/app";
+import { CROSS_REFERENCES_PROTOCOL, type ApplyProjectionInput, type ApplyProjectionResponse, type GetProjectionInput, type GetProjectionResponse, type ListBacklinksInput, type ListBacklinksResponse, type ListForwardReferencesInput, type ListForwardReferencesResponse, type CheckForwardReferencesInput, type ForwardReferenceStatus } from "./index.js";
+export type CrossReferencesSdk = Pick<BbPluginApi["sdk"], "plugins"> | Pick<PluginBrowserBbSdk, "plugins">;
+export interface CrossReferencesDescription {
+    protocol: typeof CROSS_REFERENCES_PROTOCOL;
+    version: 1;
+    legacy: boolean;
+}
+export interface CrossReferencesClient {
+    readonly pluginId: string;
+    describe(signal?: AbortSignal): Promise<CrossReferencesDescription>;
+    applyProjection(input: ApplyProjectionInput, signal?: AbortSignal): Promise<ApplyProjectionResponse>;
+    getProjection(input: GetProjectionInput, signal?: AbortSignal): Promise<GetProjectionResponse>;
+    listBacklinks(input: ListBacklinksInput, signal?: AbortSignal): Promise<ListBacklinksResponse>;
+    listForwardReferences(input: ListForwardReferencesInput, signal?: AbortSignal): Promise<ListForwardReferencesResponse>;
+    checkForwardReferences(input: CheckForwardReferencesInput, signal?: AbortSignal): Promise<ForwardReferenceStatus[]>;
+}
+export declare class CrossReferencesProtocolError extends Error {
+    readonly code = "incompatible_protocol";
+    constructor(message: string);
+}
+export interface CrossReferencesClientOptions {
+    /** Budgets may only lower the package's published upper bounds. */
+    callMs?: number;
+    describeMs?: number;
+}
+/** Explicit target, no hooks, storage, scheduling, retry or singleton. */
+export declare function createCrossReferencesClient(sdk: CrossReferencesSdk, targetPluginId?: string, options?: CrossReferencesClientOptions): CrossReferencesClient;

package/dist/types/canonical.d.ts

@@ -0,0 +1,65 @@
+export declare const PROTOCOL_VERSION: 1;
+export declare const MAX_RESOURCE_KEYS = 32;
+export declare const MAX_KEY_VALUE_BYTES = 512;
+export declare const MAX_KEY_VALUE_MATERIAL_BYTES = 8192;
+export declare const MAX_CANONICAL_IDENTITY_BYTES: number;
+export declare const MAX_PRESENTATION_BYTES: number;
+export declare const MAX_PRESENTATION_LABEL_BYTES = 256;
+export declare const MAX_PRESENTATION_DETAIL_BYTES = 1024;
+export declare const MAX_PRESENTATION_URL_BYTES = 2048;
+export declare const MAX_TARGETS = 256;
+export declare const MAX_PROJECTION_PAYLOAD_BYTES: number;
+export declare const MAX_MUTATION_ID_BYTES = 128;
+export declare const MACHINE_MONITOR_ROUTE = "/plugins/machine-monitor/machine-monitor";
+export type Presentation = {
+    label: string;
+    detail?: string;
+    url?: string;
+};
+export type ResourceIdentity = {
+    provider: string;
+    keys: Record<string, string>;
+};
+export type Resource = ResourceIdentity & {
+    presentation: Presentation;
+};
+export interface CanonicalIdentity extends ResourceIdentity {
+    canonicalKeysJson: string;
+    canonicalIdentityJson: string;
+    identityDigest: string;
+}
+export interface CanonicalResource extends Resource, CanonicalIdentity {
+    presentationJson: string;
+}
+export declare class CrossReferenceValidationError extends Error {
+    constructor(message: string);
+}
+export declare function utf8ByteLength(value: string): number;
+export declare function validateBbId(value: unknown, label: string): string;
+export declare function validateProducerPluginId(value: unknown): string;
+export declare function validateMutationId(value: unknown): string;
+export declare function validateRevision(value: unknown, label: string, minimum: number): number;
+export declare function validateDigest(value: unknown, label?: string): string;
+export declare function canonicalizeIdentity(value: ResourceIdentity): CanonicalIdentity;
+export declare function canonicalizeResource(value: Resource): CanonicalResource;
+export declare function resourceIdentityOf(resource: CanonicalResource): ResourceIdentity;
+/** The installation-local BB identity conventions used by the first slice. */
+export declare function projectIdentity(projectId: string): ResourceIdentity;
+export declare function threadIdentity(projectId: string, threadId: string): ResourceIdentity;
+export declare function machineMonitorIdentity(): ResourceIdentity;
+export declare function projectResource(projectId: string, presentation: Presentation): Resource;
+export declare function threadResource(projectId: string, threadId: string, presentation: Presentation): Resource;
+export declare function machineMonitorResource(presentation?: Presentation): Resource;
+export declare function serializeResource(resource: CanonicalResource): Resource;
+export declare function sha256Hex(value: string): string;
+export declare function projectionPayloadJson(producerPluginId: string, source: CanonicalResource, tombstone: boolean, targets: readonly CanonicalResource[]): string;
+export declare function projectionPayloadDigest(producerPluginId: string, source: CanonicalResource, tombstone: boolean, targets: readonly CanonicalResource[]): string;
+/** Exact v1 thread shape, after canonicalization has sorted its keys. */
+export declare function isExactBbThreadResource(resource: CanonicalResource): boolean;
+export declare function isUrlResource(resource: CanonicalResource): boolean;
+export declare function normalizeThreadOrUrlReference(target: Resource): CanonicalResource;
+export declare function urlResource(href: string, presentation: Omit<Presentation, "url">): Resource;
+export declare const MAX_REFERENCE_URL_BYTES = 512;
+export declare const MAX_REFERENCE_LABEL_BYTES = 256;
+export declare function hasSensitiveUrlParameter(url: URL): boolean;
+export declare function referenceLabelError(value: string): string | null;