@letta-ai/letta-code 0.25.10 → 0.26.0

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.25.10",
+  "version": "0.26.0",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
+  "packageManager": "bun@1.3.0",
   "bin": {
     "letta": "letta.js"
   },
@@ -13,7 +14,8 @@
     "scripts",
     "skills",
     "vendor",
-    "dist/types"
+    "dist/types",
+    "docs"
   ],
   "exports": {
     ".": "./letta.js",
@@ -61,6 +63,7 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^5.0.0",
     "lint-staged": "16.2.4",
+    "madge": "^8.0.0",
     "minimatch": "^10.0.3",
     "picomatch": "^2.3.1",
     "react": "18.2.0",
@@ -71,12 +74,16 @@
     "lint": "bunx --bun @biomejs/biome@2.2.5 check src",
     "fix": "bunx --bun @biomejs/biome@2.2.5 check --write src",
     "typecheck": "tsc --noEmit",
+    "check:cycles": "madge --circular --extensions ts,tsx src/",
+    "check:boundaries": "node scripts/check-layer-boundaries.js",
+    "check:exported-functions": "node scripts/check-exported-functions.js",
+    "check:filename-casing": "node scripts/check-filename-casing.js",
     "check:test-mock-isolation": "bun run scripts/check-test-mock-isolation.js",
     "check": "bun run scripts/check.js",
     "dev": "LETTA_DEBUG=${LETTA_DEBUG:-1} LETTA_RESPONSES_WS=${LETTA_RESPONSES_WS:-1} bun --loader=.md:text --loader=.mdx:text --loader=.txt:text run src/index.ts",
     "build": "node scripts/postinstall-patches.js && bun run build.js",
-    "test:update-chain:manual": "bun run src/tests/update-chain-smoke.ts --mode manual",
-    "test:update-chain:startup": "bun run src/tests/update-chain-smoke.ts --mode startup",
+    "test:update-chain:manual": "bun run src/test-utils/update-chain-smoke.ts --mode manual",
+    "test:update-chain:startup": "bun run src/test-utils/update-chain-smoke.ts --mode startup",
     "prepublishOnly": "bun run build",
     "postinstall": "node scripts/postinstall-patches.js || echo letta: vendor patches skipped && node -e \"try{require('fs').chmodSync(require('path').join(require.resolve('node-pty/package.json'),'../prebuilds/darwin-arm64/spawn-helper'),0o755)}catch(e){}\" || true"
   },

package/scripts/check-exported-functions.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Enforces that exported functions use `export function` declarations
+ * rather than `export const fn = () =>` or `export const fn = async () =>`.
+ *
+ * Rationale: `export function` declarations are greppable (`grep "export function"`
+ * reliably finds all exported functions), hoisted, and easier for agents to locate.
+ *
+ * Scope: .ts files only — NOT .tsx. React components in .tsx legitimately use
+ * `export const Foo = memo(...)` which cannot be a function declaration.
+ *
+ * Value exports (singletons, data, re-exports) are not flagged.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { glob } from "glob";
+
+const rootDir = process.cwd();
+
+// Matches: export const name = (...) => or export const name = async (...) =>
+// Also catches: export const name = () => and export const name = async () =>
+const ARROW_EXPORT = /^export const \w+ = (async )?\(/;
+
+const files = await glob("src/**/*.ts", {
+  cwd: rootDir,
+  ignore: ["**/*.test.ts", "**/*.spec.ts", "**/*.d.ts"],
+});
+
+let violations = 0;
+
+for (const file of files.sort()) {
+  const content = readFileSync(join(rootDir, file), "utf-8");
+  const lines = content.split("\n");
+
+  lines.forEach((line, i) => {
+    if (ARROW_EXPORT.test(line)) {
+      if (violations === 0) {
+        console.error("\n❌ Exported arrow functions found:\n");
+      }
+      console.error(`  ${file}:${i + 1}`);
+      console.error(`    ${line.trim()}`);
+      console.error(
+        `    ↳ Use 'export function name() {}' instead of 'export const name = () =>'\n`,
+      );
+      violations++;
+    }
+  });
+}
+
+if (violations > 0) {
+  console.error(
+    `Found ${violations} exported arrow function${violations === 1 ? "" : "s"}.`,
+  );
+  process.exit(1);
+} else {
+  console.log("✅ No exported arrow functions found.");
+}

package/scripts/check-filename-casing.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Enforces kebab-case filenames for .ts files in src/.
+ * .tsx files are exempt — PascalCase is the React component convention.
+ * .d.ts files are exempt.
+ *
+ * A filename is a violation if its stem (before the first dot) contains
+ * any uppercase letter, e.g. bootstrapHandler.ts or LocalStore.ts.
+ *
+ * Pass --staged to check only git-staged files (used in pre-commit hook).
+ */
+
+import { execSync } from "node:child_process";
+import { readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+
+const stagedOnly = process.argv.includes("--staged");
+
+function isViolation(filename) {
+  if (!filename.endsWith(".ts")) return false;
+  if (filename.endsWith(".d.ts")) return false;
+  const stem = filename.slice(0, filename.indexOf("."));
+  return /[A-Z]/.test(stem);
+}
+
+function* walkTs(dir) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) yield* walkTs(full);
+    else if (isViolation(entry)) yield full;
+  }
+}
+
+let files;
+
+if (stagedOnly) {
+  const staged = execSync("git diff --cached --name-only --diff-filter=A", {
+    encoding: "utf-8",
+  })
+    .trim()
+    .split("\n")
+    .filter((f) => f.startsWith("src/") && isViolation(basename(f)));
+  files = staged;
+} else {
+  files = [...walkTs("src")];
+}
+
+if (files.length === 0) {
+  console.log("✅ No filename casing violations found.");
+  process.exit(0);
+}
+
+console.error("\n❌ Non-kebab-case .ts filenames found:\n");
+for (const f of files) {
+  const stem = basename(f).slice(0, basename(f).indexOf("."));
+  const kebab = stem
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+  console.error(`  ${f}`);
+  console.error(`    ↳ rename to: ${basename(f).replace(stem, kebab)}\n`);
+}
+
+console.error(
+  `Found ${files.length} violation${files.length === 1 ? "" : "s"}.`,
+);
+console.error(
+  ".tsx files are exempt (PascalCase is correct for React components).\n",
+);
+process.exit(1);

package/scripts/check-layer-boundaries.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Enforces architectural import boundaries between top-level modules.
+ *
+ * Rules:
+ *   tools/              must not import from  cli/
+ *   backend/            must not import from  cli/  or  websocket/
+ *   providers/          must not import from  agent/  or  cli/
+ *   websocket/listener/ must not import from  backend/api/client  or  backend/api/conversations
+ *   telemetry/          must not import from  cli/  agent/  websocket/  or  tools/
+ *
+ * These are currently violation-free. Adding a rule here means you must
+ * also ensure no existing code violates it.
+ *
+ * To add a new rule, append an entry to RULES below.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { glob } from "glob";
+
+const rootDir = process.cwd();
+const srcDir = join(rootDir, "src");
+
+/**
+ * Each rule: files under `layer` must not contain an import from any of `forbidden`.
+ * `description` is shown on violation.
+ */
+const RULES = [
+  {
+    layer: "tools",
+    forbidden: ["cli"],
+    description:
+      "tools/ run in headless and agent contexts — they must not import from cli/",
+  },
+  {
+    layer: "backend",
+    forbidden: ["cli", "websocket"],
+    description:
+      "backend/ is a low-level abstraction — it must not import from cli/ or websocket/",
+  },
+  {
+    layer: "providers",
+    forbidden: ["agent", "cli"],
+    description:
+      "providers/ are pure LLM adapters — they must not import from agent/ or cli/",
+  },
+  {
+    layer: "websocket/listener",
+    forbidden: ["backend/api/client", "backend/api/conversations"],
+    description:
+      "websocket/listener/ uses the getBackend() abstraction — it must not import the raw API client or conversations module directly",
+  },
+  {
+    layer: "cli/app",
+    forbidden: ["backend/api/conversations"],
+    description:
+      "cli/app/ uses the getBackend() abstraction for conversation operations — it must not import the raw conversations module directly",
+  },
+  {
+    layer: "telemetry",
+    forbidden: ["cli", "agent", "websocket", "tools"],
+    description:
+      "telemetry/ is a leaf observer — it must not import from cli/, agent/, websocket/, or tools/ (only backend/api/ for submitting data is permitted)",
+  },
+];
+
+// Matches: import ... from "@/forbidden/..." (static imports only)
+function buildPattern(forbidden) {
+  return new RegExp(`from\\s+["'\`]@/(${forbidden.join("|")})/`, "g");
+}
+
+let violations = 0;
+
+for (const rule of RULES) {
+  const files = await glob(`src/${rule.layer}/**/*.{ts,tsx}`, {
+    cwd: rootDir,
+    ignore: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"],
+  });
+
+  const pattern = buildPattern(rule.forbidden);
+
+  for (const file of files.sort()) {
+    const content = readFileSync(join(rootDir, file), "utf-8");
+    const lines = content.split("\n");
+
+    lines.forEach((line, i) => {
+      // Reset lastIndex for global regex reuse
+      pattern.lastIndex = 0;
+      if (pattern.test(line)) {
+        if (violations === 0) {
+          console.error("\n❌ Layer boundary violations found:\n");
+        }
+        console.error(`  ${file}:${i + 1}`);
+        console.error(`    ${line.trim()}`);
+        console.error(`    ↳ ${rule.description}\n`);
+        violations++;
+      }
+    });
+  }
+}
+
+if (violations > 0) {
+  console.error(
+    `Found ${violations} boundary violation${violations === 1 ? "" : "s"}.`,
+  );
+  console.error(
+    "Fix by moving the helper to a shared layer (utils/, types/) or inverting the dependency.\n",
+  );
+  process.exit(1);
+} else {
+  console.log("✅ No layer boundary violations found.");
+}

package/scripts/check-test-mock-isolation.js

@@ -8,7 +8,7 @@ const TESTS_DIR_ENV = "LETTA_MOCK_ISOLATION_TESTS_DIR";
 const rootDir = process.cwd();
 const testsDir = process.env[TESTS_DIR_ENV]
   ? resolve(process.env[TESTS_DIR_ENV])
-  : join(rootDir, "src", "tests");
+  : join(rootDir, "src");
 
 const FORBIDDEN_MOCK_MODULES = new Map([
   [
@@ -41,24 +41,24 @@ const COMPLETE_EXPORT_MOCK_MODULES = new Set([
 // explicit test override helper. If a new top-level mock is truly unavoidable,
 // add a file+module entry here in the same PR with a clear explanation.
 const ALLOWED_TOP_LEVEL_MOCKS = new Set([
-  "src/tests/channels/discord-registry.test.ts::../../backend/api/client",
-  "src/tests/channels/slack-adapter-interop.test.ts::../../channels/slack/media",
-  "src/tests/channels/slack-adapter-interop.test.ts::../../channels/slack/runtime",
-  "src/tests/channels/slack-adapter.test.ts::../../channels/slack/media",
-  "src/tests/channels/slack-adapter.test.ts::../../channels/slack/runtime",
-  "src/tests/channels/telegram-adapter.test.ts::../../channels/telegram/runtime",
-  "src/tests/cli/message-search-cache-warm.test.ts::../../backend/api/search",
-  "src/tests/hooks/prompt-executor.test.ts::../../backend/api/generate",
-  "src/tests/tools/memory-apply-patch.test.ts::../../backend/api/client",
-  "src/tests/tools/memory-tool.test.ts::../../backend/api/client",
-  "src/tests/tools/toolset-client-tool-rule-cleanup.test.ts::../../backend/api/client",
-  "src/tests/tools/toolset-memfs-detach.test.ts::../../backend/api/client",
-  "src/tests/websocket/listen-client-concurrency.test.ts::../../agent/approval-execution",
-  "src/tests/websocket/listen-client-concurrency.test.ts::../../agent/approval-recovery",
-  "src/tests/websocket/listen-client-concurrency.test.ts::../../agent/message",
-  "src/tests/websocket/listen-client-concurrency.test.ts::../../backend/api/client",
-  "src/tests/websocket/listen-client-concurrency.test.ts::../../cli/helpers/approvalClassification",
-  "src/tests/websocket/listen-client-concurrency.test.ts::../../cli/helpers/stream",
+  "src/channels/discord-registry.test.ts::../backend/api/client",
+  "src/channels/slack-adapter-interop.test.ts::./slack/media",
+  "src/channels/slack-adapter-interop.test.ts::./slack/runtime",
+  "src/channels/slack-adapter.test.ts::./slack/media",
+  "src/channels/slack-adapter.test.ts::./slack/runtime",
+  "src/channels/telegram-adapter.test.ts::./telegram/runtime",
+  "src/cli/message-search-cache-warm.test.ts::../backend/api/search",
+  "src/hooks/prompt-executor.test.ts::../backend/api/generate",
+  "src/tools/memory-apply-patch.test.ts::../backend/api/client",
+  "src/tools/memory-tool.test.ts::../backend/api/client",
+  "src/tools/toolset-client-tool-rule-cleanup.test.ts::../backend/api/client",
+  "src/tools/toolset-memfs-detach.test.ts::../backend/api/client",
+  "src/websocket/listen-client-concurrency.test.ts::../agent/approval-execution",
+  "src/websocket/listen-client-concurrency.test.ts::../agent/approval-recovery",
+  "src/websocket/listen-client-concurrency.test.ts::../agent/message",
+  "src/websocket/listen-client-concurrency.test.ts::../backend/api/client",
+  "src/websocket/listen-client-concurrency.test.ts::../cli/helpers/approvalClassification",
+  "src/websocket/listen-client-concurrency.test.ts::../cli/helpers/stream",
 ]);
 
 const mockModulePattern = /\bmock\.module\s*\(\s*(["'`])([^"'`]+)\1/g;

package/scripts/check.js

@@ -1,56 +1,76 @@
 #!/usr/bin/env bun
-// Script to run linting and type checking with helpful error messages
 
-import { $ } from "bun";
+const LABEL_WIDTH = 32;
 
-console.log("🔍 Running lint and type checks...\n");
+function formatLabel(name) {
+  const dots = ".".repeat(Math.max(3, LABEL_WIDTH - name.length - 1));
+  return `${name} ${dots}`;
+}
+
+function parseFileCount(output) {
+  const m = output.match(/(?:Processed|Checked) ([\d,]+) files/);
+  return m ? Number(m[1].replace(/,/g, "")) : null;
+}
+
+const checks = [
+  { name: "circular dependencies", script: ["check:cycles", "--no-spinner"] },
+  { name: "layer boundaries", script: ["check:boundaries"] },
+  { name: "exported function style", script: ["check:exported-functions"] },
+  { name: "filename casing", script: ["check:filename-casing"] },
+  { name: "test mock isolation", script: ["check:test-mock-isolation"] },
+  { name: "biome", script: ["lint"] },
+  { name: "typescript", script: ["typecheck"] },
+];
+
+const N = checks.length;
+let failed = 0;
+const wallStart = performance.now();
+
+for (let i = 0; i < N; i++) {
+  const { name, script } = checks[i];
+  const t0 = performance.now();
 
-let failed = false;
+  const proc = Bun.spawn(["bun", "run", ...script], {
+    cwd: process.cwd(),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
 
-// Run test mock isolation check
-console.log("🧪 Checking Bun module mock isolation...");
-try {
-  await $`bun run check:test-mock-isolation`;
-  console.log("✅ Mock isolation check passed\n");
-} catch (error) {
-  console.error("❌ Mock isolation check failed\n");
-  console.error(
-    "Fix the unsafe mock.module() usage above. Prefer explicit test override helpers or scoped mocks with afterEach(mock.restore).\n",
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  const elapsed = ((performance.now() - t0) / 1000).toFixed(1);
+  const ok = exitCode === 0;
+  const combined = stdout + stderr;
+  const count = parseFileCount(combined);
+  const countStr = count ? `  (${count.toLocaleString()} files)` : "";
+
+  process.stdout.write(
+    `[${i + 1}/${N}] ${formatLabel(name)} ${ok ? "PASS" : "FAIL"}  ${elapsed}s${countStr}\n`,
   );
-  failed = true;
-}
 
-// Run lint
-console.log("📝 Running Biome linter...");
-try {
-  await $`bun run lint`;
-  console.log("✅ Linting passed\n");
-} catch (error) {
-  console.error("❌ Linting failed\n");
-  console.error("To fix automatically, run:");
-  console.error("  bun run fix\n");
-  failed = true;
+  if (!ok) {
+    failed++;
+    const lines = combined
+      .trim()
+      .split("\n")
+      .filter((l) => l.trim());
+    for (const line of lines) {
+      process.stderr.write(`       ${line}\n`);
+    }
+    process.stderr.write("\n");
+  }
 }
 
-// Run typecheck
-console.log("🔎 Running TypeScript type checker...");
-try {
-  await $`bun run typecheck`;
-  console.log("✅ Type checking passed\n");
-} catch (error) {
-  console.error("❌ Type checking failed\n");
-  console.error("Fix the type errors shown above, then run:");
-  console.error("  bun run typecheck\n");
-  failed = true;
-}
+const total = ((performance.now() - wallStart) / 1000).toFixed(1);
+process.stdout.write("\n");
 
-if (failed) {
-  console.error("❌ Checks failed. Please fix the errors above.");
-  console.error("\nQuick commands:");
-  console.error("  bun run fix       # Auto-fix linting issues");
-  console.error("  bun run typecheck # Check types only");
-  console.error("  bun run check     # Run both checks");
+if (failed === 0) {
+  process.stdout.write(`✓ ${N} checks passed in ${total}s\n`);
+} else {
+  process.stderr.write(`✗ ${failed} of ${N} checks failed in ${total}s\n`);
   process.exit(1);
 }
-
-console.log("✅ All checks passed!");