@cat-factory/kernel 0.254.0 → 0.255.0

package/dist/ports/document-source.d.ts

@@ -53,6 +53,36 @@ export interface DocumentSourceProvider {
     resolveImplicitConnection?(workspaceId: string): Promise<NormalizedConnection | null>;
     /** Resolve a stable page id from raw user input (a bare id or a page URL); null if unparseable. */
     parseRef(input: string): string | null;
+    /**
+     * The canonical web URL for a page id, rebuilt WITHOUT a fetch: what a pasted share link is
+     * trimmed to once its title segment and tracking params are dropped. It is the half of
+     * {@link parseRef} an attach surface needs to SHOW someone what their paste resolved to,
+     * before any credential is spent or any row is written.
+     *
+     * OPTIONAL, and the absence is a real fact rather than an unimplemented method: a Confluence
+     * page id needs the connection's site base URL and a Linear document id the workspace slug,
+     * neither of which the id carries, so those providers can only answer by fetching. The GitHub
+     * docs source omits it for a different reason worth keeping distinct: the id carries everything
+     * a link needs EXCEPT the host, and the host is a deployment fact (a GitLab-backed deployment
+     * reaches the same source through the VCS adapter), so any URL built here would name the wrong
+     * one half the time. A caller renders the id itself in all these cases; it must NOT read the
+     * absence as a failed resolution.
+     */
+    canonicalUrl?(externalId: string): string | null;
+    /**
+     * The narrowing qualifier `input` carried that {@link parseRef}'s id does NOT cover, or null.
+     *
+     * A design source's ref grammar is two-level: a file/project, optionally narrowed to a
+     * frame/screen. When the qualifier is one the parser cannot read, `parseRef` deliberately falls
+     * back to the CONTAINER rather than guessing which frame was meant, which silently widens the
+     * reference from one frame to the whole file. That widening is invisible in the result (a valid
+     * id, a valid canonical URL), so the provider that dropped it is the only thing that can say so.
+     *
+     * OPTIONAL: a source with a single-level grammar has no narrowing to drop, and its absence means
+     * exactly that. Implemented by the design sources (Figma, Zeplin). PURE, taking the same raw
+     * input `parseRef` took, so it costs a pre-flight nothing.
+     */
+    droppedScope?(input: string, externalId: string): string | null;
     /**
      * Fetch a single page by its id using the connection credentials. `workspaceId` is
      * the workspace on whose behalf the read happens: a provider that authenticates

package/dist/ports/document-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-source.d.ts","sourceRoot":"","sources":["../../src/ports/document-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAahE,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAExD,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,WAAW,EAAE,mBAAmB,CAAA;IAChC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAA;IAC7C;;;OAGG;IACH,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAAA;IACrE;;;;;;;;;;OAUG;IACH,yBAAyB,CAAC,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAA;IACrF,mGAAmG;IACnG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACtC;;;;;;OAMG;IACH,aAAa,CACX,WAAW,EAAE,mBAAmB,EAChC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CAAA;IAC3B;;;;;;;OAOG;IACH,YAAY,CACV,WAAW,EAAE,mBAAmB,EAChC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAAA;IAClB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,CACL,WAAW,EAAE,mBAAmB,EAChC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAA;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,+FAA+F;IAC/F,KAAK,CACH,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,EAC1B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAAA;IAC3B;;;;;OAKG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACnG;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,4BAA4B;AACtC,uEAAuE;AACrE;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC5D,mEAAmE;GACjE;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE;AACpC,6FAA6F;GAC3F;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAA;AAEtC,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;CACtC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,SAAS,cAAc,EAAE,GACnC,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAA;CACzC;AAED,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,GAAG,CAAC,IAAI,EAAE,kBAAkB,GAAG,sBAAsB,GAAG,SAAS,CAAA;IACjE,4EAA4E;IAC5E,IAAI,IAAI,sBAAsB,EAAE,CAAA;CACjC"}
+{"version":3,"file":"document-source.d.ts","sourceRoot":"","sources":["../../src/ports/document-source.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/kernel",
-  "version": "0.254.0",
+  "version": "0.255.0",
   "description": "Shared vocabulary, pure logic, and port interfaces for the Agent Architecture Board.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   "dependencies": {
     "ai": "^7.0.51",
     "yaml": "^2.9.0",
-    "@cat-factory/contracts": "0.255.0"
+    "@cat-factory/contracts": "0.256.0"
   },
   "devDependencies": {
     "@stryker-mutator/core": "9.6.1",