larkit 0.0.0-stage → 0.1.0

package/src/shared/config.js

@@ -0,0 +1,90 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  DATA_DIR,
+  HOME_CONFIG_FILE,
+  PROJECT_CONFIG_FILE,
+} from "./paths.js";
+import { readJson } from "./util.js";
+
+/**
+ * Configuration layers (lowest to highest precedence):
+ *   1. <data dir>/config.json     (legacy / machine level)
+ *   2. ~/.larkit/config.json      (user level)
+ *   3. ./larkit.config.json       (project level, next to the app you build)
+ * Environment variables still win inside getAppCredentials().
+ */
+export function loadConfig() {
+  const machine = readJson(path.join(DATA_DIR, "config.json"), {});
+  const home = readJson(HOME_CONFIG_FILE, {});
+  const project = readJson(PROJECT_CONFIG_FILE, {});
+  const merged = {
+    ...machine,
+    ...home,
+    ...project,
+    apps: { ...(machine.apps || {}), ...(home.apps || {}), ...(project.apps || {}) },
+    console: {
+      ...(machine.console || {}),
+      ...(home.console || {}),
+      ...(project.console || {}),
+    },
+  };
+  return merged;
+}
+
+export function getAppCredentials(appId, config = loadConfig()) {
+  if (
+    process.env.FEISHU_APP_ID &&
+    process.env.FEISHU_APP_SECRET &&
+    (!appId || appId === process.env.FEISHU_APP_ID)
+  ) {
+    return {
+      app_id: appId || process.env.FEISHU_APP_ID,
+      app_secret: process.env.FEISHU_APP_SECRET,
+      source: "env",
+    };
+  }
+  const apps = config.apps || {};
+  if (appId) {
+    const direct = apps[appId];
+    if (direct?.app_secret) {
+      return { app_id: appId, app_secret: direct.app_secret, source: "config" };
+    }
+    for (const [name, value] of Object.entries(apps)) {
+      if (value?.app_id === appId && value?.app_secret) {
+        return {
+          app_id: appId,
+          app_secret: value.app_secret,
+          source: `config:${name}`,
+        };
+      }
+    }
+  }
+  const first = Object.entries(apps).find(
+    ([, value]) => value?.app_id && value?.app_secret,
+  );
+  if (first) {
+    return {
+      app_id: first[1].app_id,
+      app_secret: first[1].app_secret,
+      source: `config:${first[0]}`,
+    };
+  }
+  return null;
+}
+
+export function configForMcp() {
+  const config = loadConfig();
+  return {
+    default_profile: config.defaultProfile || config.console?.profile || null,
+    apps: Object.keys(config.apps || {}),
+  };
+}
+
+export function ensureConfigFile() {
+  return fs.existsSync(PROJECT_CONFIG_FILE);
+}
+
+export function configPath() {
+  return path.resolve(PROJECT_CONFIG_FILE);
+}

package/src/shared/paths.js

@@ -0,0 +1,151 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * PKG_ROOT is the immutable package directory (src/, skills/, protocol data).
+ * LARKIT_HOME is the mutable per-user directory created by `larkit init`.
+ *
+ * A git checkout keeps using the historical in-repo `.larkit-data/` layout so
+ * `pnpm index` / `pnpm verify` continue to work unchanged.  An installed CLI
+ * (global install or `npx larkit`) has no `.larkit-data/` next to the package
+ * and therefore stores everything under `~/.larkit/`.
+ */
+export const PKG_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../..",
+);
+
+/** Backwards-compatible alias: code that reads bundled assets uses ROOT. */
+export const ROOT = PKG_ROOT;
+
+const REPO_DATA_DIR = path.join(PKG_ROOT, ".larkit-data");
+export const IS_REPO_CHECKOUT =
+  fs.existsSync(path.join(PKG_ROOT, ".git")) ||
+  fs.existsSync(path.join(PKG_ROOT, "pnpm-lock.yaml"));
+
+const HAS_REPO_DATA = fs.existsSync(REPO_DATA_DIR);
+
+export const LARKIT_HOME = process.env.LARKIT_HOME
+  ? path.resolve(process.env.LARKIT_HOME)
+  : path.join(os.homedir(), ".larkit");
+
+export const DATA_DIR = process.env.LARKIT_DATA_DIR
+  ? path.resolve(process.env.LARKIT_DATA_DIR)
+  : HAS_REPO_DATA
+    ? REPO_DATA_DIR
+    : path.join(LARKIT_HOME, "data");
+
+export const VERIFIED_DIR = process.env.LARKIT_VERIFIED_DIR
+  ? path.resolve(process.env.LARKIT_VERIFIED_DIR)
+  : HAS_REPO_DATA
+    ? path.join(PKG_ROOT, "verified_truths")
+    : path.join(LARKIT_HOME, "verified_truths");
+
+export const RAW_DIR = path.join(DATA_DIR, "raw");
+export const CACHE_DIR = path.join(DATA_DIR, "cache");
+export const DEB_ROOT = path.join(RAW_DIR, "deb-root");
+export const FEISHU_APP_DIR = path.join(
+  DEB_ROOT,
+  "opt",
+  "bytedance",
+  "feishu",
+);
+export const ELECTRON_EXTRACT_DIR = path.join(
+  DATA_DIR,
+  "extracted",
+  "electron",
+);
+export const FORMATTED_DIR = path.join(DATA_DIR, "formatted");
+export const TRUTH_DB = path.join(DATA_DIR, "truth.db");
+export const TRUTH_META = path.join(DATA_DIR, "truth.meta.json");
+export const WEB_INDEX = path.join(RAW_DIR, "web-index.json");
+export const ELECTRON_INDEX = path.join(RAW_DIR, "electron-index.json");
+export const EXTRACT_MANIFEST = path.join(RAW_DIR, "manifest.extract.json");
+export const FORMAT_MANIFEST = path.join(
+  FORMATTED_DIR,
+  ".format-manifest.json",
+);
+export const ANCHORS_JSONL = path.join(RAW_DIR, "anchors.jsonl");
+export const PROTOCOL_CATALOG_JSON = path.join(
+  RAW_DIR,
+  "protocol-catalog.json",
+);
+export const PROTOCOL_DOCS_JSON = path.join(RAW_DIR, "protocol-docs.json");
+
+export const PROTOCOL_REFERENCE_DIR = path.join(
+  PKG_ROOT,
+  "src",
+  "protocol",
+  "data",
+  "reference",
+);
+
+/** Immutable assets shipped inside the npm package. */
+export const SKILL_SOURCE_DIR = path.join(PKG_ROOT, "skills", "larkit");
+
+/** Mutable per-user locations. */
+export const INSTALL_STATE_FILE = path.join(LARKIT_HOME, "install.json");
+export const INSTALL_LOCK_FILE = path.join(LARKIT_HOME, ".install.lock");
+export const CLI_INSTALL_DIR = path.join(LARKIT_HOME, "cli");
+export const DOWNLOAD_DIR = path.join(LARKIT_HOME, "downloads");
+export const LOG_FILE = path.join(LARKIT_HOME, "install.log");
+export const BIN_DIR = process.env.LARKIT_BIN_DIR
+  ? path.resolve(process.env.LARKIT_BIN_DIR)
+  : path.join(os.homedir(), ".local", "bin");
+export const MCP_CONFIG_FILE = path.join(LARKIT_HOME, "mcp.json");
+
+/** Configuration: project-local overrides user-level defaults. */
+export const PROJECT_CONFIG_FILE = process.env.LARKIT_CONFIG
+  ? path.resolve(process.env.LARKIT_CONFIG)
+  : path.join(process.cwd(), "larkit.config.json");
+export const HOME_CONFIG_FILE = path.join(LARKIT_HOME, "config.json");
+/** Backwards-compatible exports. */
+export const CONFIG_FILE = PROJECT_CONFIG_FILE;
+export const LOCAL_CONFIG_FILE = HOME_CONFIG_FILE;
+
+export const AUTH_CREDENTIALS_FILE = path.join(
+  LARKIT_HOME,
+  "credentials.json",
+);
+export const AUTH_CONFIG_FILE = path.join(LARKIT_HOME, "config.json");
+export const CONSOLE_RECIPES_FILE = path.join(
+  DATA_DIR,
+  "console-api-recipes.json",
+);
+
+/** Build inputs (only needed for `larkit init --from-assets`). */
+export const WEB_DUMP_DIR = process.env.LARKIT_WEB_DUMP
+  ? path.resolve(process.env.LARKIT_WEB_DUMP)
+  : path.join(PKG_ROOT, "feishu-web-dump");
+export const WEB_SUMMARY = path.join(WEB_DUMP_DIR, "summary.json");
+export const DEB_FILE = process.env.LARKIT_DEB
+  ? path.resolve(process.env.LARKIT_DEB)
+  : [
+      path.join(PKG_ROOT, "feishu-linux.deb"),
+      path.join(LARKIT_HOME, "assets", "feishu-linux.deb"),
+    ].find((candidate) => fs.existsSync(candidate)) ||
+    path.join(PKG_ROOT, "feishu-linux.deb");
+
+/** Render a user-facing relative path that does not leak the install layout. */
+export function displayPath(target) {
+  const resolved = path.resolve(target);
+  const formatted = path.resolve(FORMATTED_DIR);
+  const verified = path.resolve(VERIFIED_DIR);
+  const root = path.resolve(ROOT);
+  if (resolved === formatted || resolved.startsWith(formatted + path.sep)) {
+    return `formatted/${path.relative(formatted, resolved).split(path.sep).join("/")}`;
+  }
+  if (resolved === verified || resolved.startsWith(verified + path.sep)) {
+    return `verified_truths/${path.relative(verified, resolved).split(path.sep).join("/")}`;
+  }
+  if (resolved === root || resolved.startsWith(root + path.sep)) {
+    return path.relative(root, resolved).split(path.sep).join("/");
+  }
+  const data = path.resolve(DATA_DIR);
+  if (resolved === data || resolved.startsWith(data + path.sep)) {
+    return path.relative(data, resolved).split(path.sep).join("/");
+  }
+  return resolved;
+}

package/src/shared/quiet.js

@@ -0,0 +1,12 @@
+/**
+ * node:sqlite is stable enough for this local index but still emits an
+ * ExperimentalWarning on Node 24.  Suppress only that warning so CLI JSON
+ * output stays clean; all other warnings pass through.
+ */
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = (warning, ...args) => {
+  const text =
+    typeof warning === "string" ? warning : warning?.message || String(warning);
+  if (/SQLite is an experimental feature/i.test(text)) return;
+  return originalEmitWarning(warning, ...args);
+};

package/src/shared/util.js

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+export function writeJson(file, value) {
+  ensureDir(path.dirname(file));
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+export function sha1(data) {
+  return createHash("sha1").update(data).digest("hex");
+}
+
+export function sha256(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+export function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+
+export function relativeTo(base, target) {
+  return toPosix(path.relative(base, target));
+}
+
+/** Resolve a user supplied relative path inside base, rejecting traversal. */
+export function safeJoin(base, rel) {
+  const clean = String(rel || "").replace(/^[/\\]+/, "");
+  const resolved = path.resolve(base, clean);
+  const prefix = path.resolve(base) + path.sep;
+  if (resolved !== path.resolve(base) && !resolved.startsWith(prefix)) {
+    throw new Error(`path escapes root: ${rel}`);
+  }
+  return resolved;
+}
+
+export function walkFiles(dir, options = {}) {
+  const {
+    extensions = null,
+    skipDirs = new Set([
+      "node_modules",
+      ".git",
+      "i18n",
+      "locales",
+      "__tests__",
+      "test",
+    ]),
+    maxFileBytes = Infinity,
+    includeHidden = false,
+  } = options;
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  const stack = [dir];
+  while (stack.length) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!includeHidden && entry.name.startsWith(".")) continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name)) continue;
+        stack.push(full);
+      } else if (entry.isFile()) {
+        if (extensions && !extensions.has(path.extname(entry.name).toLowerCase())) {
+          continue;
+        }
+        try {
+          const st = fs.statSync(full);
+          if (st.size > maxFileBytes || st.size === 0) continue;
+          out.push({ path: full, size: st.size, mtimeMs: st.mtimeMs });
+        } catch {
+          // ignore unreadable files
+        }
+      }
+    }
+  }
+  out.sort((a, b) => a.path.localeCompare(b.path));
+  return out;
+}
+
+export function truncate(value, max = 300) {
+  const s = String(value ?? "");
+  return s.length <= max ? s : `${s.slice(0, Math.max(0, max - 1))}…`;
+}
+
+export function oneLine(value, max = 300) {
+  return truncate(String(value ?? "").replace(/\s+/g, " ").trim(), max);
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function fileSizeMiB(bytes) {
+  return `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+}
+
+export function log(...args) {
+  console.error(...args);
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}

package/src/truth/fts.js

@@ -0,0 +1,24 @@
+/** FTS helpers shared by the indexer and the query layer. */
+
+export function normalizeSearchText(value) {
+  return String(value ?? "")
+    .toLowerCase()
+    .replace(/[_/.:#-]+/g, " ")
+    .replace(/[^\p{L}\p{N}\s]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function buildFtsQuery(query, { conjunction = false } = {}) {
+  const normalized = normalizeSearchText(query);
+  if (!normalized) return "";
+  const terms = [...new Set(normalized.split(" ").filter(Boolean))].slice(0, 12);
+  return terms
+    .map((term) => `"${term.replace(/"/g, "")}"*`)
+    .join(conjunction ? " AND " : " OR ");
+}
+
+export function searchTextFor(parts) {
+  const raw = parts.filter(Boolean).join(" ");
+  return `${raw}\n${normalizeSearchText(raw)}`;
+}