gnosys 5.8.2 → 5.8.3

package/dist/lib/idFormat.d.ts

@@ -19,6 +19,11 @@
  */
 import type { GnosysDB } from "./db.js";
 export type IdFormat = "short" | "long" | "raw";
+export declare function isTtyStdout(): boolean;
+/** Build the gnosys:// URI for a memory id. Encodes the id defensively. */
+export declare function memoryUri(id: string): string;
+/** Wrap `display` in OSC8 escapes pointing at `uri`. Caller decides when to use. */
+export declare function osc8Wrap(uri: string, display: string): string;
 /**
  * Format a single memory ID for display.
  *
@@ -26,6 +31,22 @@ export type IdFormat = "short" | "long" | "raw";
  * scoped, or when lookup failed. In that case the project segment is omitted.
  */
 export declare function formatMemoryId(id: string, projectName: string | null | undefined, format?: IdFormat): string;
+/**
+ * Same as `formatMemoryId`, but wraps the result in an OSC8 hyperlink
+ * pointing at `gnosys://memory/<id>` when stdout is a TTY.
+ *
+ * In OSC8-aware terminals (iTerm2, Ghostty, Kitty, WezTerm) the citation
+ * renders underlined and the user can click / cmd-click / right-click-copy
+ * the URI. In every other context (pipes, CI logs, `--json` consumers,
+ * `less`) the function returns plain text exactly like `formatMemoryId`.
+ *
+ * Always emits the FULL id in the underlying URI (so right-click-copy
+ * gives back something useful) even when the visible text is the
+ * truncated `short` form.
+ */
+export declare function formatMemoryIdHyperlink(id: string, projectName: string | null | undefined, format?: IdFormat, options?: {
+    tty?: boolean;
+}): string;
 /**
  * Build a single-shot {project_id → project_name} lookup map.
  *

package/dist/lib/idFormat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idFormat.d.ts","sourceRoot":"","sources":["../../src/lib/idFormat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAa,MAAM,SAAS,CAAC;AAEnD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAIhD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,MAAM,GAAE,QAAkB,GACzB,MAAM,CAcR;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAGjE"}
+{"version":3,"file":"idFormat.d.ts","sourceRoot":"","sources":["../../src/lib/idFormat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAa,MAAM,SAAS,CAAC;AAEnD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAuBhD,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,MAAM,GAAE,QAAkB,GACzB,MAAM,CAcR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,MAAM,GAAE,QAAkB,EAC1B,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1B,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAGjE"}

package/dist/lib/idFormat.js

@@ -18,6 +18,34 @@
  * across one project. Users who script against IDs should pass `--id-format raw`.
  */
 const SHORT_ULID_PREFIX = 8;
+// ─── OSC8 hyperlink helpers ─────────────────────────────────────────────
+//
+// v5.8.3 (#91): emit clickable links for memory IDs in OSC8-supporting
+// terminals (iTerm2, Ghostty, Kitty, WezTerm, modern gnome-terminal).
+// The escape sequence is `\x1b]8;;<URI>\x1b\\<text>\x1b]8;;\x1b\\`. A
+// terminal that doesn't understand it ignores the escapes and prints
+// only `<text>`, so this is safe everywhere — but we only emit when
+// stdout is a TTY to keep pipes/CI logs clean.
+//
+// URI scheme: `gnosys://memory/<id>`. No OS-level handler is required
+// for visual underline/click affordance to render; users who want
+// "click → open in gnosys" can register a URL handler later, but the
+// out-of-the-box value is the visual hint + copy-URL menu in the
+// terminal.
+const OSC8_START = "\x1b]8;;";
+const OSC8_BREAK = "\x1b\\";
+const OSC8_END = "\x1b]8;;\x1b\\";
+export function isTtyStdout() {
+    return Boolean(process.stdout.isTTY);
+}
+/** Build the gnosys:// URI for a memory id. Encodes the id defensively. */
+export function memoryUri(id) {
+    return `gnosys://memory/${encodeURIComponent(id)}`;
+}
+/** Wrap `display` in OSC8 escapes pointing at `uri`. Caller decides when to use. */
+export function osc8Wrap(uri, display) {
+    return `${OSC8_START}${uri}${OSC8_BREAK}${display}${OSC8_END}`;
+}
 /**
  * Format a single memory ID for display.
  *
@@ -39,6 +67,26 @@ export function formatMemoryId(id, projectName, format = "short") {
         return renderedId;
     return `${projectName} · ${renderedId}`;
 }
+/**
+ * Same as `formatMemoryId`, but wraps the result in an OSC8 hyperlink
+ * pointing at `gnosys://memory/<id>` when stdout is a TTY.
+ *
+ * In OSC8-aware terminals (iTerm2, Ghostty, Kitty, WezTerm) the citation
+ * renders underlined and the user can click / cmd-click / right-click-copy
+ * the URI. In every other context (pipes, CI logs, `--json` consumers,
+ * `less`) the function returns plain text exactly like `formatMemoryId`.
+ *
+ * Always emits the FULL id in the underlying URI (so right-click-copy
+ * gives back something useful) even when the visible text is the
+ * truncated `short` form.
+ */
+export function formatMemoryIdHyperlink(id, projectName, format = "short", options) {
+    const display = formatMemoryId(id, projectName, format);
+    const tty = options?.tty ?? isTtyStdout();
+    if (!tty)
+        return display;
+    return osc8Wrap(memoryUri(id), display);
+}
 /**
  * Build a single-shot {project_id → project_name} lookup map.
  *

package/dist/lib/idFormat.js.map

@@ -1 +1 @@
-{"version":3,"file":"idFormat.js","sourceRoot":"","sources":["../../src/lib/idFormat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,EAAU,EACV,WAAsC,EACtC,SAAmB,OAAO;IAE1B,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAEhC,IAAI,UAAU,GAAG,EAAE,CAAC;IACpB,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACvB,yEAAyE;QACzE,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,OAAO,GAAG,CAAC,GAAG,iBAAiB,EAAE,CAAC;YAC/D,UAAU,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,GAAG,iBAAiB,CAAC,GAAG,CAAC;QAClE,CAAC;IACH,CAAC;IAED,IAAI,CAAC,WAAW;QAAE,OAAO,UAAU,CAAC;IACpC,OAAO,GAAG,WAAW,MAAM,UAAU,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,EAAY;IACjD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,MAAM,IAAI,GAAG,EAAE,CAAC,cAAc,EAAiB,CAAC;IAChD,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI;YAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3E,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"idFormat.js","sourceRoot":"","sources":["../../src/lib/idFormat.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnosys",
-  "version": "5.8.2",
+  "version": "5.8.3",
   "description": "Gnosys — Persistent Memory for AI Agents. Sandbox-first runtime, central SQLite brain, federated search, Dream Mode, Web Knowledge Base, Obsidian export.",
   "type": "module",
   "main": "dist/index.js",