@eltonssouza/development-utility-kit 1.0.0

package/.claude/skills/honcho-memory/lib/honcho-client.js

@@ -0,0 +1,363 @@
+/**
+ * honcho-client.js
+ *
+ * Honcho v3 REST client using native fetch (Bun/Node 18+).
+ * All public functions return null on any error — never throw to caller.
+ * API: https://honcho.pazzne.cloud (verified via /openapi.json 2026-05-26)
+ *
+ * Key deviations from DISCOVERY doc (see docs/api-endpoints-verified.md):
+ * - No "apps" or "users" concept — workspace = app, peer = user identity
+ * - Individual message DELETE does not exist; deleteSession deletes the session
+ * - Soft-delete: PUT /messages/{id} with body { metadata: { deleted: true } }
+ * - listMemories uses POST /messages/list (not GET)
+ * - saveMemory uses batch endpoint with required peer_id per message
+ * - listMemories and searchMemories filter out metadata.deleted = true client-side
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+const CONFIG_PATH = "C:\\Users\\elton\\.honcho\\config.json";
+
+/**
+ * Load and parse config from C:\Users\elton\.honcho\config.json.
+ * Returns null if file missing or unparseable.
+ * apiKey is never logged.
+ */
+export function loadConfig() {
+  try {
+    if (!existsSync(CONFIG_PATH)) {
+      return null;
+    }
+    const raw = readFileSync(CONFIG_PATH, "utf8");
+    const cfg = JSON.parse(raw);
+    if (!cfg.apiKey || !cfg.endpoint?.baseUrl) {
+      return null;
+    }
+    return cfg;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create an AbortController-backed timeout promise.
+ * Returns { controller, timeoutId, signal }.
+ */
+function makeTimeout(ms) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), ms);
+  return { controller, timeoutId, signal: controller.signal };
+}
+
+/**
+ * Execute a fetch with timeout. Returns Response or null on error/timeout.
+ * Never throws.
+ */
+async function fetchSafe(url, options, timeoutMs) {
+  const { signal, timeoutId } = makeTimeout(timeoutMs);
+  try {
+    const resp = await fetch(url, { ...options, signal });
+    clearTimeout(timeoutId);
+    return resp;
+  } catch {
+    clearTimeout(timeoutId);
+    return null;
+  }
+}
+
+/**
+ * Parse JSON body from response. Returns null on failure.
+ */
+async function parseJson(resp) {
+  if (!resp) return null;
+  try {
+    if (!resp.ok) return null;
+    return await resp.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a Honcho v3 client bound to a specific base URL, API key, and timeout.
+ *
+ * @param {object} opts
+ * @param {string} opts.baseUrl - e.g. "https://honcho.pazzne.cloud/v3"
+ * @param {string} opts.apiKey  - bearer token (never logged)
+ * @param {number} [opts.timeoutMs=450] - request timeout in milliseconds
+ */
+export function createClient({ baseUrl, apiKey, timeoutMs = 450 }) {
+  const base = baseUrl.replace(/\/$/, "");
+
+  function headers() {
+    return {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    };
+  }
+
+  /**
+   * GET or CREATE a workspace (maps to "app" in DISCOVERY terminology).
+   * POST /v3/workspaces with idempotent id.
+   *
+   * @param {string} workspaceId - workspace identifier (^[a-zA-Z0-9_-]+$)
+   * @returns {object|null} workspace object or null on error
+   */
+  async function getOrCreateApp(workspaceId) {
+    const resp = await fetchSafe(
+      `${base}/workspaces`,
+      {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify({ id: workspaceId }),
+      },
+      timeoutMs
+    );
+    return parseJson(resp);
+  }
+
+  /**
+   * GET or CREATE a session within a workspace.
+   * POST /v3/workspaces/{workspaceId}/sessions with idempotent id.
+   *
+   * @param {string} workspaceId
+   * @param {string} sessionId - session identifier (per-directory, derived from CWD)
+   * @param {object} [metadata={}] - optional metadata
+   * @returns {object|null}
+   */
+  async function getOrCreateSession(workspaceId, sessionId, metadata = {}) {
+    const resp = await fetchSafe(
+      `${base}/workspaces/${encodeURIComponent(workspaceId)}/sessions`,
+      {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify({ id: sessionId, metadata }),
+      },
+      timeoutMs
+    );
+    return parseJson(resp);
+  }
+
+  /**
+   * Save a memory (message) into a session.
+   * POST /v3/workspaces/{ws}/sessions/{session}/messages (batch endpoint).
+   *
+   * @param {string} workspaceId
+   * @param {string} sessionId
+   * @param {string} peerId - peer/user identity (peerName from config)
+   * @param {string} content - memory text content
+   * @param {object} [metadata={}] - e.g. { type: "explicit", source: "user", ... }
+   * @returns {object|null} created message batch result or null on error
+   */
+  async function saveMemory(workspaceId, sessionId, peerId, content, metadata = {}) {
+    const resp = await fetchSafe(
+      `${base}/workspaces/${encodeURIComponent(workspaceId)}/sessions/${encodeURIComponent(sessionId)}/messages`,
+      {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify({
+          messages: [
+            {
+              content,
+              peer_id: peerId,
+              metadata,
+            },
+          ],
+        }),
+      },
+      timeoutMs
+    );
+    return parseJson(resp);
+  }
+
+  /**
+   * Search memories semantically for a peer within a workspace.
+   * POST /v3/workspaces/{ws}/peers/{peerId}/search
+   * Client-side post-filter removes any message with metadata.deleted = true (BR-008).
+   *
+   * @param {string} workspaceId
+   * @param {string} peerId
+   * @param {string} query - search query text
+   * @param {number} [limit=5] - max results (1-100)
+   * @returns {object|null} search results (items filtered) or null on error
+   */
+  async function searchMemories(workspaceId, peerId, query, limit = 5) {
+    const resp = await fetchSafe(
+      `${base}/workspaces/${encodeURIComponent(workspaceId)}/peers/${encodeURIComponent(peerId)}/search`,
+      {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify({ query, limit }),
+      },
+      timeoutMs
+    );
+    const data = await parseJson(resp);
+    if (!data) return null;
+    // Filter soft-deleted items client-side (BR-008)
+    if (Array.isArray(data.items)) {
+      data.items = data.items.filter((m) => m.metadata?.deleted !== true);
+    }
+    return data;
+  }
+
+  /**
+   * List messages (memories) in a session.
+   * POST /v3/workspaces/{ws}/sessions/{session}/messages/list
+   * Client-side post-filter removes any message with metadata.deleted = true (BR-008).
+   *
+   * @param {string} workspaceId
+   * @param {string} sessionId
+   * @param {object} [filters={}] - optional filters
+   * @returns {object|null} Page[Message] (items filtered) or null on error
+   */
+  async function listMemories(workspaceId, sessionId, filters = {}) {
+    const body = Object.keys(filters).length > 0 ? { filters } : {};
+    const resp = await fetchSafe(
+      `${base}/workspaces/${encodeURIComponent(workspaceId)}/sessions/${encodeURIComponent(sessionId)}/messages/list`,
+      {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify(body),
+      },
+      timeoutMs
+    );
+    const data = await parseJson(resp);
+    if (!data) return null;
+    // Filter soft-deleted items client-side (BR-008)
+    if (Array.isArray(data.items)) {
+      data.items = data.items.filter((m) => m.metadata?.deleted !== true);
+    }
+    return data;
+  }
+
+  /**
+   * Delete a session (and all its messages).
+   * DELETE /v3/workspaces/{ws}/sessions/{sessionId}
+   *
+   * @param {string} workspaceId
+   * @param {string} sessionId
+   * @returns {object|null} result or null on error
+   */
+  async function deleteMemory(workspaceId, sessionId) {
+    const resp = await fetchSafe(
+      `${base}/workspaces/${encodeURIComponent(workspaceId)}/sessions/${encodeURIComponent(sessionId)}`,
+      {
+        method: "DELETE",
+        headers: headers(),
+      },
+      timeoutMs
+    );
+    if (!resp) return null;
+    try {
+      // 204 No Content is a success response for DELETE
+      if (resp.status === 204 || resp.ok) {
+        return { deleted: true, sessionId };
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Soft-delete a specific message by setting metadata.deleted = true.
+   * PUT /v3/workspaces/{ws}/sessions/{sessionId}/messages/{messageId}
+   * body: { "metadata": { "deleted": true } }
+   *
+   * @param {string} workspaceId
+   * @param {string} sessionId
+   * @param {string} messageId
+   * @returns {object|null} updated message or null on error
+   */
+  async function softDeleteMemory(workspaceId, sessionId, messageId) {
+    const resp = await fetchSafe(
+      `${base}/workspaces/${encodeURIComponent(workspaceId)}/sessions/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}`,
+      {
+        method: "PUT",
+        headers: headers(),
+        body: JSON.stringify({ metadata: { deleted: true } }),
+      },
+      timeoutMs
+    );
+    return parseJson(resp);
+  }
+
+  return {
+    getOrCreateApp,
+    getOrCreateSession,
+    saveMemory,
+    searchMemories,
+    listMemories,
+    deleteMemory,
+    softDeleteMemory,
+  };
+}
+
+// Module-level convenience functions that read config automatically.
+// These are the "standalone" exports that tests can call directly.
+
+/** @returns {object|null} */
+export async function getOrCreateApp(workspaceId) {
+  const cfg = loadConfig();
+  if (!cfg) return null;
+  const client = createClient({ baseUrl: cfg.endpoint.baseUrl, apiKey: cfg.apiKey, timeoutMs: cfg.timeoutMs ?? 450 });
+  return client.getOrCreateApp(workspaceId);
+}
+
+/** @returns {object|null} */
+export async function getOrCreateSession(workspaceId, sessionId, metadata = {}) {
+  const cfg = loadConfig();
+  if (!cfg) return null;
+  const client = createClient({ baseUrl: cfg.endpoint.baseUrl, apiKey: cfg.apiKey, timeoutMs: cfg.timeoutMs ?? 450 });
+  return client.getOrCreateSession(workspaceId, sessionId, metadata);
+}
+
+/** @returns {object|null} */
+export async function saveMemory(workspaceId, sessionId, peerId, content, metadata = {}) {
+  const cfg = loadConfig();
+  if (!cfg) return null;
+  const client = createClient({ baseUrl: cfg.endpoint.baseUrl, apiKey: cfg.apiKey, timeoutMs: cfg.timeoutMs ?? 450 });
+  return client.saveMemory(workspaceId, sessionId, peerId, content, metadata);
+}
+
+/** @returns {object|null} */
+export async function searchMemories(workspaceId, peerId, query, limit = 5) {
+  const cfg = loadConfig();
+  if (!cfg) return null;
+  const client = createClient({ baseUrl: cfg.endpoint.baseUrl, apiKey: cfg.apiKey, timeoutMs: cfg.timeoutMs ?? 450 });
+  return client.searchMemories(workspaceId, peerId, query, limit);
+}
+
+/** @returns {object|null} */
+export async function listMemories(workspaceId, sessionId, filters = {}) {
+  const cfg = loadConfig();
+  if (!cfg) return null;
+  const client = createClient({ baseUrl: cfg.endpoint.baseUrl, apiKey: cfg.apiKey, timeoutMs: cfg.timeoutMs ?? 450 });
+  return client.listMemories(workspaceId, sessionId, filters);
+}
+
+/** @returns {object|null} */
+export async function deleteMemory(workspaceId, sessionId) {
+  const cfg = loadConfig();
+  if (!cfg) return null;
+  const client = createClient({ baseUrl: cfg.endpoint.baseUrl, apiKey: cfg.apiKey, timeoutMs: cfg.timeoutMs ?? 450 });
+  return client.deleteMemory(workspaceId, sessionId);
+}
+
+/**
+ * Soft-delete a specific message by setting metadata.deleted = true.
+ * PUT /v3/workspaces/{ws}/sessions/{sessionId}/messages/{messageId}
+ *
+ * @param {string} workspaceId
+ * @param {string} sessionId
+ * @param {string} messageId
+ * @returns {object|null} updated message or null on error
+ */
+export async function softDeleteMemory(workspaceId, sessionId, messageId) {
+  const cfg = loadConfig();
+  if (!cfg) return null;
+  const client = createClient({ baseUrl: cfg.endpoint.baseUrl, apiKey: cfg.apiKey, timeoutMs: cfg.timeoutMs ?? 450 });
+  return client.softDeleteMemory(workspaceId, sessionId, messageId);
+}

package/.claude/skills/honcho-memory/lib/memory-injector.js

@@ -0,0 +1,93 @@
+/**
+ * memory-injector.js
+ *
+ * Formats a list of MemoryFact objects into a [HONCHO MEMORY] block
+ * suitable for injection into a Claude Code system prompt extension.
+ *
+ * Rules (per plan):
+ * - FR-005: builds [HONCHO MEMORY]...[/HONCHO MEMORY] block with metadata
+ * - BR-007: total block limited to 2000 characters
+ * - NFR-006: prefix = [HONCHO MEMORY], suffix = [/HONCHO MEMORY]
+ */
+
+const MAX_CHARS = 2000;
+const OPEN_TAG = "[HONCHO MEMORY]";
+const CLOSE_TAG = "[/HONCHO MEMORY]";
+
+/**
+ * @typedef {object} MemoryFact
+ * @property {string} content - memory text content
+ * @property {object} [metadata] - associated metadata
+ * @property {string} [metadata.type] - "explicit" | "inferred" | "project-context"
+ * @property {string} [metadata.timestamp] - ISO-8601 timestamp
+ * @property {string} [metadata.project] - project name
+ * @property {string} [metadata.source] - "user" | "inference"
+ */
+
+/**
+ * Format a single MemoryFact into a text block line.
+ * @param {MemoryFact} memory
+ * @param {number} index - 1-based index
+ * @returns {string}
+ */
+function formatMemory(memory, index) {
+  const meta = memory.metadata ?? {};
+  const parts = [];
+
+  if (meta.type) parts.push(`type:${meta.type}`);
+  if (meta.timestamp) parts.push(`ts:${meta.timestamp}`);
+  if (meta.project) parts.push(`project:${meta.project}`);
+
+  const metaStr = parts.length > 0 ? ` [${parts.join(" | ")}]` : "";
+  return `${index}. ${memory.content}${metaStr}`;
+}
+
+/**
+ * Build the [HONCHO MEMORY] injection block from an array of MemoryFact objects.
+ * Returns an empty string when memories array is empty.
+ * Total output is capped at MAX_CHARS (2000) — memories are truncated to fit.
+ *
+ * @param {MemoryFact[]} memories - ordered list of memory facts to inject
+ * @returns {string} formatted block or empty string
+ */
+export function buildContextBlock(memories) {
+  if (!Array.isArray(memories) || memories.length === 0) {
+    return "";
+  }
+
+  const lines = [];
+  for (let i = 0; i < memories.length; i++) {
+    lines.push(formatMemory(memories[i], i + 1));
+  }
+
+  const inner = lines.join("\n");
+  const full = `${OPEN_TAG}\n${inner}\n${CLOSE_TAG}`;
+
+  if (full.length <= MAX_CHARS) {
+    return full;
+  }
+
+  // Truncate: build block greedily, memory by memory, until limit reached
+  let accumulated = `${OPEN_TAG}\n`;
+  const closingNeeded = `\n${CLOSE_TAG}`;
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineToAdd = (i === 0 ? "" : "\n") + lines[i];
+    const projected = accumulated + lineToAdd + closingNeeded;
+    if (projected.length <= MAX_CHARS) {
+      accumulated += lineToAdd;
+    } else {
+      // Try to fit a truncated version of this line
+      const budgetForLine = MAX_CHARS - accumulated.length - closingNeeded.length - (i === 0 ? 0 : 1);
+      if (budgetForLine > 10) {
+        // Enough room to add a partial line
+        const prefix = i === 0 ? "" : "\n";
+        const truncated = lines[i].slice(0, budgetForLine);
+        accumulated += prefix + truncated;
+      }
+      break;
+    }
+  }
+
+  return accumulated + closingNeeded;
+}

package/.claude/skills/honcho-memory/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "honcho-memory",
+  "version": "0.1.0",
+  "description": "Honcho v3 memory integration skill for Claude Code — semantic memory persistence across sessions",
+  "type": "module",
+  "scripts": {
+    "test": "bun run tests/t001-api-endpoints-verified.test.js && bun run tests/t002-structure.test.js && bun run tests/t003-honcho-client.test.js && bun run tests/t004-soft-delete.test.js && bun run tests/t005-memory-injector.test.js && bun run tests/t006-on-prompt-submit.test.js && bun run tests/t007-on-stop.test.js && bun run tests/t008-cli.test.js && bun run tests/t009-setup.test.js && bun run tests/t010-skill-md.test.js && bun run tests/t011-settings-hooks.test.js && bun run tests/t012-docs-update.test.js && bun run tests/t013-smoke-e2e.test.js",
+    "test:sprint0": "bun run tests/t001-api-endpoints-verified.test.js && bun run tests/t002-structure.test.js && bun run tests/t003-honcho-client.test.js",
+    "test:sprint1": "bun run tests/t004-soft-delete.test.js && bun run tests/t005-memory-injector.test.js && bun run tests/t006-on-prompt-submit.test.js && bun run tests/t007-on-stop.test.js",
+    "test:sprint2": "bun run tests/t008-cli.test.js && bun run tests/t009-setup.test.js",
+    "test:sprint3": "bun run tests/t010-skill-md.test.js && bun run tests/t011-settings-hooks.test.js && bun run tests/t012-docs-update.test.js && bun run tests/t013-smoke-e2e.test.js",
+    "test:t001": "bun run tests/t001-api-endpoints-verified.test.js",
+    "test:t002": "bun run tests/t002-structure.test.js",
+    "test:t003": "bun run tests/t003-honcho-client.test.js",
+    "test:t004": "bun run tests/t004-soft-delete.test.js",
+    "test:t005": "bun run tests/t005-memory-injector.test.js",
+    "test:t006": "bun run tests/t006-on-prompt-submit.test.js",
+    "test:t007": "bun run tests/t007-on-stop.test.js",
+    "test:t008": "bun run tests/t008-cli.test.js",
+    "test:t009": "bun run tests/t009-setup.test.js",
+    "test:t010": "bun run tests/t010-skill-md.test.js",
+    "test:t011": "bun run tests/t011-settings-hooks.test.js",
+    "test:t012": "bun run tests/t012-docs-update.test.js",
+    "test:t013": "bun run tests/t013-smoke-e2e.test.js",
+    "setup": "bun run scripts/setup.js",
+    "setup:dry": "bun run scripts/setup.js --dry-run",
+    "status": "bun run scripts/cli.js status"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}