@eltonssouza/development-utility-kit 1.0.0

package/.claude/skills/honcho-memory/scripts/cli.js

@@ -0,0 +1,370 @@
+/**
+ * cli.js — Honcho memory skill CLI dispatcher
+ *
+ * Subcommands:
+ *   status          — print connection status, memory count, enabled flags
+ *   save <text>     — save an explicit memory, print the ID
+ *   search <query>  — search memories (peer-scoped), print top-N formatted
+ *   list            — list memories for the current session (sha256(CWD)[:16])
+ *   forget <id>     — soft-delete memory via PUT metadata.deleted=true; exit 1 if no ID
+ *
+ * Env vars:
+ *   HONCHO_DRY_RUN=1   — skip real Honcho calls; emit simulated output
+ *   HONCHO_BASE_URL    — override base URL from config
+ *   HONCHO_TIMEOUT_MS  — override timeout in ms
+ *
+ * Exit codes:
+ *   0 — success
+ *   1 — error (e.g. forget without ID, unknown subcommand, fatal)
+ *
+ * API key is never printed to stdout/stderr.
+ */
+
+import { createHash } from "crypto";
+import { createClient, loadConfig } from "../lib/honcho-client.js";
+
+const DRY_RUN = process.env.HONCHO_DRY_RUN === "1";
+
+/** Derive session ID from CWD: sha256(CWD)[:16] */
+function deriveSessionId(cwd) {
+  return createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+}
+
+function log(msg) {
+  process.stdout.write(msg + "\n");
+}
+
+function warn(msg) {
+  process.stderr.write("HONCHO_WARN: " + msg + "\n");
+}
+
+/** Build effective config from file + env overrides. Returns null if missing/invalid. */
+function getEffectiveConfig() {
+  const cfg = loadConfig();
+
+  if (process.env.HONCHO_BASE_URL) {
+    return {
+      apiKey: cfg?.apiKey ?? "dry-run-key",
+      peerName: cfg?.peerName ?? "elton",
+      workspace: cfg?.workspace ?? "claude_code",
+      endpoint: { baseUrl: process.env.HONCHO_BASE_URL },
+      enabled: cfg?.enabled !== false,
+      topN: cfg?.topN ?? 5,
+      timeoutMs: process.env.HONCHO_TIMEOUT_MS
+        ? parseInt(process.env.HONCHO_TIMEOUT_MS, 10)
+        : (cfg?.timeoutMs ?? 450),
+      inferenceEnabled: cfg?.inferenceEnabled ?? false,
+    };
+  }
+
+  if (!cfg) return null;
+
+  if (process.env.HONCHO_TIMEOUT_MS) {
+    cfg.timeoutMs = parseInt(process.env.HONCHO_TIMEOUT_MS, 10);
+  }
+
+  return cfg;
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+
+async function cmdStatus() {
+  if (DRY_RUN) {
+    const cfg = loadConfig();
+    log("connection: DRY_RUN");
+    log("memories: 0");
+    log(`enabled: ${cfg?.enabled !== false ? "true" : "false"}`);
+    log(`inferenceEnabled: ${cfg?.inferenceEnabled === true ? "true" : "false"}`);
+    process.exit(0);
+  }
+
+  const cfg = getEffectiveConfig();
+  if (!cfg) {
+    log("connection: FAIL");
+    log("memories: 0");
+    log("enabled: false");
+    log("inferenceEnabled: false");
+    process.exit(0);
+  }
+
+  const client = createClient({
+    baseUrl: cfg.endpoint.baseUrl,
+    apiKey: cfg.apiKey,
+    timeoutMs: cfg.timeoutMs ?? 450,
+  });
+
+  const workspace = cfg.workspace ?? "claude_code";
+  const cwd = process.cwd();
+  const sessionId = deriveSessionId(cwd);
+
+  // Test connectivity by attempting to get/create app
+  const appResult = await client.getOrCreateApp(workspace);
+  const connected = appResult !== null;
+
+  // Count memories for the current session
+  let memCount = 0;
+  if (connected) {
+    const listResult = await client.listMemories(workspace, sessionId, {});
+    if (listResult && Array.isArray(listResult.items)) {
+      memCount = listResult.items.length;
+    }
+  }
+
+  log(`connection: ${connected ? "OK" : "FAIL"}`);
+  log(`memories: ${memCount}`);
+  log(`enabled: ${cfg.enabled !== false ? "true" : "false"}`);
+  log(`inferenceEnabled: ${cfg.inferenceEnabled === true ? "true" : "false"}`);
+  process.exit(0);
+}
+
+async function cmdSave(text) {
+  const cwd = process.cwd();
+  const sessionId = deriveSessionId(cwd);
+  const project = cwd.split(/[/\\]/).pop() ?? "unknown";
+
+  if (DRY_RUN) {
+    const dryId = `dry-${Date.now()}`;
+    log(JSON.stringify({
+      dryRun: true,
+      action: "save",
+      id: dryId,
+      content: (text ?? "").slice(0, 100),
+    }));
+    process.exit(0);
+  }
+
+  const cfg = getEffectiveConfig();
+  if (!cfg) {
+    warn("No valid config found — cannot save memory");
+    process.exit(0);
+  }
+
+  const workspace = cfg.workspace ?? "claude_code";
+  const peerId = cfg.peerName ?? "elton";
+
+  const client = createClient({
+    baseUrl: cfg.endpoint.baseUrl,
+    apiKey: cfg.apiKey,
+    timeoutMs: cfg.timeoutMs ?? 450,
+  });
+
+  const result = await client.saveMemory(workspace, sessionId, peerId, text ?? "", {
+    type: "explicit",
+    source: "user",
+    project,
+    directory: cwd,
+    timestamp: new Date().toISOString(),
+  });
+
+  if (result) {
+    const id = result.id ?? result.items?.[0]?.id ?? "unknown";
+    log(`Saved memory. ID: ${id}`);
+  } else {
+    warn("Failed to save memory — Honcho may be unreachable");
+  }
+  process.exit(0);
+}
+
+async function cmdList() {
+  const cwd = process.cwd();
+  const sessionId = deriveSessionId(cwd);
+
+  if (DRY_RUN) {
+    log(JSON.stringify({
+      dryRun: true,
+      action: "list",
+      sessionId,
+      items: [],
+    }));
+    process.exit(0);
+  }
+
+  const cfg = getEffectiveConfig();
+  if (!cfg) {
+    warn("No valid config found — cannot list memories");
+    process.exit(0);
+  }
+
+  const workspace = cfg.workspace ?? "claude_code";
+
+  const client = createClient({
+    baseUrl: cfg.endpoint.baseUrl,
+    apiKey: cfg.apiKey,
+    timeoutMs: cfg.timeoutMs ?? 450,
+  });
+
+  const result = await client.listMemories(workspace, sessionId, {});
+  if (!result) {
+    warn("Failed to list memories — Honcho may be unreachable");
+    process.exit(0);
+  }
+
+  const items = result.items ?? [];
+  if (items.length === 0) {
+    log("No memories found for current session.");
+    process.exit(0);
+  }
+
+  for (let i = 0; i < items.length; i++) {
+    const m = items[i];
+    const meta = m.metadata ?? {};
+    const ts = meta.timestamp ?? "";
+    const type = meta.type ?? "unknown";
+    log(`[${i + 1}] id:${m.id ?? "?"} type:${type} ts:${ts}`);
+    log(`    ${m.content ?? ""}`);
+  }
+  process.exit(0);
+}
+
+async function cmdSearch(query) {
+  const cfg = getEffectiveConfig();
+  const cwd = process.cwd();
+
+  if (DRY_RUN) {
+    log(JSON.stringify({
+      dryRun: true,
+      action: "search",
+      query: (query ?? "").slice(0, 100),
+      items: [],
+    }));
+    process.exit(0);
+  }
+
+  if (!cfg) {
+    warn("No valid config found — cannot search memories");
+    process.exit(0);
+  }
+
+  const workspace = cfg.workspace ?? "claude_code";
+  const peerId = cfg.peerName ?? "elton";
+  const topN = cfg.topN ?? 5;
+
+  const client = createClient({
+    baseUrl: cfg.endpoint.baseUrl,
+    apiKey: cfg.apiKey,
+    timeoutMs: cfg.timeoutMs ?? 450,
+  });
+
+  const result = await client.searchMemories(workspace, peerId, query ?? "", topN);
+  if (!result) {
+    warn("Failed to search memories — Honcho may be unreachable");
+    process.exit(0);
+  }
+
+  const items = result.items ?? [];
+  if (items.length === 0) {
+    log("No memories found matching your query.");
+    process.exit(0);
+  }
+
+  for (let i = 0; i < items.length; i++) {
+    const m = items[i];
+    const meta = m.metadata ?? {};
+    const type = meta.type ?? "unknown";
+    const score = m.score != null ? ` score:${m.score.toFixed(3)}` : "";
+    log(`[${i + 1}] id:${m.id ?? "?"} type:${type}${score}`);
+    log(`    ${m.content ?? ""}`);
+  }
+  process.exit(0);
+}
+
+async function cmdForget(id) {
+  if (!id) {
+    process.stderr.write("Error: forget requires a memory ID. Usage: cli.js forget <id>\n");
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  const sessionId = deriveSessionId(cwd);
+
+  if (DRY_RUN) {
+    log(JSON.stringify({
+      dryRun: true,
+      action: "forget",
+      method: "PUT",
+      id,
+      sessionId,
+      metadata: { deleted: true },
+    }));
+    process.exit(0);
+  }
+
+  const cfg = getEffectiveConfig();
+  if (!cfg) {
+    warn("No valid config found — cannot forget memory");
+    process.exit(0);
+  }
+
+  const workspace = cfg.workspace ?? "claude_code";
+
+  const client = createClient({
+    baseUrl: cfg.endpoint.baseUrl,
+    apiKey: cfg.apiKey,
+    timeoutMs: cfg.timeoutMs ?? 450,
+  });
+
+  const result = await client.softDeleteMemory(workspace, sessionId, id);
+  if (result) {
+    log(JSON.stringify({
+      action: "forget",
+      method: "PUT",
+      id,
+      result,
+    }));
+  } else {
+    warn(`Failed to soft-delete memory id=${id} — Honcho may be unreachable or ID not found`);
+  }
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Main dispatcher
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const [subcommand, ...rest] = process.argv.slice(2);
+
+  switch (subcommand) {
+    case "status":
+      await cmdStatus();
+      break;
+
+    case "save":
+      await cmdSave(rest.join(" ") || undefined);
+      break;
+
+    case "list":
+      await cmdList();
+      break;
+
+    case "search":
+      await cmdSearch(rest.join(" ") || undefined);
+      break;
+
+    case "forget":
+      await cmdForget(rest[0]);
+      break;
+
+    default:
+      if (!subcommand) {
+        process.stderr.write(
+          "Usage: cli.js <subcommand> [args]\n" +
+          "Subcommands: status, save <text>, list, search <query>, forget <id>\n"
+        );
+      } else {
+        process.stderr.write(
+          `Unknown subcommand: "${subcommand}"\n` +
+          "Usage: cli.js <subcommand> [args]\n" +
+          "Subcommands: status, save <text>, list, search <query>, forget <id>\n"
+        );
+      }
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  warn("Unexpected error: " + (err?.message ?? String(err)));
+  process.exit(1);
+});

package/.claude/skills/honcho-memory/scripts/setup.js

@@ -0,0 +1,109 @@
+/**
+ * setup.js — Honcho memory skill setup wizard
+ *
+ * Verifies connection to Honcho, checks config validity, and optionally
+ * migrates legacy memory/*.md files to Honcho.
+ *
+ * Usage:
+ *   bun run scripts/setup.js           # interactive wizard
+ *   bun run scripts/setup.js --dry-run # non-interactive verification only
+ *
+ * Exit codes:
+ *   0 — success or graceful degradation
+ *   1 — fatal error (missing bun, config parse error, etc.)
+ */
+
+import { existsSync, readdirSync } from "fs";
+import { join, resolve } from "path";
+import { createClient, loadConfig } from "../lib/honcho-client.js";
+
+const DRY_RUN = process.argv.includes("--dry-run");
+const CONFIG_PATH = "C:\\Users\\elton\\.honcho\\config.json";
+
+function log(msg) {
+  process.stdout.write(msg + "\n");
+}
+
+function warn(msg) {
+  process.stderr.write("HONCHO_WARN: " + msg + "\n");
+}
+
+async function checkConnection(cfg) {
+  const client = createClient({
+    baseUrl: cfg.endpoint.baseUrl,
+    apiKey: cfg.apiKey,
+    timeoutMs: cfg.timeoutMs ?? 450,
+  });
+
+  // Use the workspace from config to test connectivity
+  const workspaceId = cfg.hosts?.claude_code?.workspace ?? "claude_code";
+  const result = await client.getOrCreateApp(workspaceId);
+  return result !== null;
+}
+
+function countMemoryFiles(cwd) {
+  const memDir = join(cwd, "memory");
+  if (!existsSync(memDir)) return 0;
+  try {
+    return readdirSync(memDir).filter((f) => f.endsWith(".md")).length;
+  } catch {
+    return 0;
+  }
+}
+
+async function main() {
+  // Step 1: verify config exists and is parseable
+  if (!existsSync(CONFIG_PATH)) {
+    warn(`Config file not found: ${CONFIG_PATH}`);
+    log("Config: MISSING");
+    log("Connection: FAIL");
+    if (DRY_RUN) {
+      log("DRY_RUN: config missing, cannot proceed");
+    }
+    process.exit(0); // graceful degradation
+  }
+
+  const cfg = loadConfig();
+  if (!cfg) {
+    warn("Config file exists but failed to parse or is missing required fields");
+    log("Config: INVALID");
+    log("Connection: FAIL");
+    if (DRY_RUN) {
+      log("DRY_RUN: config invalid, cannot proceed");
+    }
+    process.exit(0); // graceful degradation
+  }
+
+  log("Config valid");
+
+  // Step 2: check connection
+  const connected = await checkConnection(cfg);
+
+  if (connected) {
+    log("Connection OK");
+  } else {
+    warn("Could not reach Honcho at " + cfg.endpoint.baseUrl);
+    log("Connection FAIL");
+  }
+
+  // Step 3: dry-run mode — report memory files and exit
+  if (DRY_RUN) {
+    const cwd = process.cwd();
+    const memCount = countMemoryFiles(cwd);
+    if (memCount > 0) {
+      log(`DRY_RUN: would migrate ${memCount} files`);
+    } else {
+      log("DRY_RUN: no memory files found");
+    }
+    process.exit(0);
+  }
+
+  // Step 4: interactive mode (future — not implemented in Sprint 0)
+  log("Setup complete. Run with --dry-run for non-interactive verification.");
+  process.exit(0);
+}
+
+main().catch((err) => {
+  warn("Unexpected error in setup: " + (err?.message ?? String(err)));
+  process.exit(0); // graceful degradation
+});

package/.claude/skills/honcho-memory/tests/t001-api-endpoints-verified.test.js

@@ -0,0 +1,89 @@
+/**
+ * T-001: Verify Honcho v3 endpoints documented correctly
+ *
+ * Failing tests to be written BEFORE implementation.
+ * These tests confirm the api-endpoints-verified.md file:
+ * - exists
+ * - contains a table with 6+ endpoints
+ * - contains a verifiedAt ISO-8601 field
+ * - each endpoint row has method, path, and verified status
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+const SKILL_DIR = new URL("../", import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, "$1");
+const DOCS_DIR = join(SKILL_DIR, "docs");
+const TARGET_FILE = join(DOCS_DIR, "api-endpoints-verified.md");
+
+function readFile() {
+  return readFileSync(TARGET_FILE, "utf8");
+}
+
+// Test 1: file must exist
+const test1 = () => {
+  if (!existsSync(TARGET_FILE)) {
+    throw new Error(`api-endpoints-verified.md does not exist at: ${TARGET_FILE}`);
+  }
+  console.log("PASS: api-endpoints-verified.md exists");
+};
+
+// Test 2: must contain verifiedAt ISO-8601
+const test2 = () => {
+  const content = readFile();
+  const iso8601Pattern = /verifiedAt[:\s]+\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+  if (!iso8601Pattern.test(content)) {
+    throw new Error("api-endpoints-verified.md missing verifiedAt ISO-8601 field");
+  }
+  console.log("PASS: verifiedAt ISO-8601 present");
+};
+
+// Test 3: must have markdown table with 6+ endpoint rows
+const test3 = () => {
+  const content = readFile();
+  // Count lines that look like markdown table rows with | separators
+  const tableRows = content
+    .split("\n")
+    .filter((line) => line.trim().startsWith("|") && !line.includes("---") && !line.includes("Operação") && !line.includes("Operation") && !line.includes("Method") && !line.includes("Método"));
+  if (tableRows.length < 6) {
+    throw new Error(`Expected 6+ endpoint rows in table, found ${tableRows.length}`);
+  }
+  console.log(`PASS: table contains ${tableRows.length} endpoint rows (>= 6)`);
+};
+
+// Test 4: must contain expected operations
+const test4 = () => {
+  const content = readFile();
+  const requiredOps = ["getOrCreateApp", "getOrCreateSession", "saveMemory", "searchMemories", "listMemories", "deleteMemory"];
+  const missing = requiredOps.filter((op) => !content.includes(op));
+  if (missing.length > 0) {
+    throw new Error(`Missing operations in doc: ${missing.join(", ")}`);
+  }
+  console.log("PASS: all 6 required operations documented");
+};
+
+// Test 5: must contain HTTP methods GET/POST/DELETE
+const test5 = () => {
+  const content = readFile();
+  for (const method of ["GET", "POST", "DELETE"]) {
+    if (!content.includes(method)) {
+      throw new Error(`Missing HTTP method ${method} in documentation`);
+    }
+  }
+  console.log("PASS: HTTP methods GET, POST, DELETE present");
+};
+
+// Run all tests
+let failed = 0;
+const tests = [test1, test2, test3, test4, test5];
+for (const t of tests) {
+  try {
+    t();
+  } catch (e) {
+    console.error(`FAIL: ${e.message}`);
+    failed++;
+  }
+}
+
+console.log(`\nResults: ${tests.length - failed}/${tests.length} passed`);
+process.exit(failed > 0 ? 1 : 0);

package/.claude/skills/honcho-memory/tests/t002-structure.test.js

@@ -0,0 +1,97 @@
+/**
+ * T-002: Verify package.json + directory structure
+ *
+ * Failing tests to be written BEFORE implementation.
+ * Verifies:
+ * - package.json exists with "type": "module" (ESM)
+ * - lib/, hooks/, scripts/ directories exist
+ * - bun install succeeds (exit code 0)
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+
+const SKILL_DIR = new URL("../", import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, "$1");
+const PKG_FILE = join(SKILL_DIR, "package.json");
+
+function readPkg() {
+  return JSON.parse(readFileSync(PKG_FILE, "utf8"));
+}
+
+// Test 1: package.json must exist
+const test1 = () => {
+  if (!existsSync(PKG_FILE)) {
+    throw new Error(`package.json does not exist at: ${PKG_FILE}`);
+  }
+  console.log("PASS: package.json exists");
+};
+
+// Test 2: package.json must have "type": "module"
+const test2 = () => {
+  const pkg = readPkg();
+  if (pkg.type !== "module") {
+    throw new Error(`Expected "type": "module" in package.json, got: "${pkg.type}"`);
+  }
+  console.log('PASS: package.json has "type": "module"');
+};
+
+// Test 3: package.json must have a name field
+const test3 = () => {
+  const pkg = readPkg();
+  if (!pkg.name) {
+    throw new Error("package.json missing 'name' field");
+  }
+  console.log(`PASS: package.json name = "${pkg.name}"`);
+};
+
+// Test 4: lib/ directory must exist
+const test4 = () => {
+  const libDir = join(SKILL_DIR, "lib");
+  if (!existsSync(libDir)) {
+    throw new Error(`lib/ directory does not exist at: ${libDir}`);
+  }
+  console.log("PASS: lib/ directory exists");
+};
+
+// Test 5: hooks/ directory must exist
+const test5 = () => {
+  const hooksDir = join(SKILL_DIR, "hooks");
+  if (!existsSync(hooksDir)) {
+    throw new Error(`hooks/ directory does not exist at: ${hooksDir}`);
+  }
+  console.log("PASS: hooks/ directory exists");
+};
+
+// Test 6: scripts/ directory must exist
+const test6 = () => {
+  const scriptsDir = join(SKILL_DIR, "scripts");
+  if (!existsSync(scriptsDir)) {
+    throw new Error(`scripts/ directory does not exist at: ${scriptsDir}`);
+  }
+  console.log("PASS: scripts/ directory exists");
+};
+
+// Test 7: package.json scripts must include "test"
+const test7 = () => {
+  const pkg = readPkg();
+  if (!pkg.scripts || !pkg.scripts.test) {
+    throw new Error("package.json missing scripts.test");
+  }
+  console.log(`PASS: package.json scripts.test = "${pkg.scripts.test}"`);
+};
+
+// Run all tests
+let failed = 0;
+const tests = [test1, test2, test3, test4, test5, test6, test7];
+for (const t of tests) {
+  try {
+    t();
+  } catch (e) {
+    console.error(`FAIL: ${e.message}`);
+    failed++;
+  }
+}
+
+console.log(`\nResults: ${tests.length - failed}/${tests.length} passed`);
+process.exit(failed > 0 ? 1 : 0);