codelark 0.1.0

package/scripts/build-preflight.d.ts

@@ -0,0 +1,21 @@
+export function readPackageJson(packageJsonUrl: string | URL): Promise<{ dependencies?: Record<string, string> }>;
+
+export function hasInstalledPackage(
+  dependencyName: string,
+  options?: {
+    accessFile?: (path: string) => Promise<void>;
+    resolvePaths?: (dependencyName: string) => string[] | null;
+  },
+): Promise<boolean>;
+
+export function findMissingRuntimeDependencies(
+  dependencies: Record<string, string> | undefined,
+  options?: {
+    accessFile?: (path: string) => Promise<void>;
+    resolvePaths?: (dependencyName: string) => string[] | null;
+  },
+): Promise<string[]>;
+
+export function findMissingPackageJsonRuntimeDependencies(packageJsonUrl: string | URL): Promise<string[]>;
+
+export function formatMissingRuntimeDependenciesMessage(missingDependencies: string[]): string;

package/scripts/build-preflight.js

@@ -0,0 +1,70 @@
+import { access, readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const missingPackagePathErrorCodes = new Set(['ENOENT', 'ENOTDIR']);
+
+export async function readPackageJson(packageJsonUrl) {
+  const raw = await readFile(packageJsonUrl, 'utf8');
+  return JSON.parse(raw);
+}
+
+export async function hasInstalledPackage(dependencyName, options = {}) {
+  const accessFile = options.accessFile ?? access;
+  const resolvePaths = options.resolvePaths ?? (() => []);
+
+  for (const nodeModulesPath of resolvePaths(dependencyName) ?? []) {
+    const packageJsonPath = path.join(nodeModulesPath, dependencyName, 'package.json');
+
+    try {
+      await accessFile(packageJsonPath);
+      return true;
+    } catch (error) {
+      if (!missingPackagePathErrorCodes.has(error?.code)) {
+        throw error;
+      }
+    }
+  }
+
+  return false;
+}
+
+export async function findMissingRuntimeDependencies(dependencies, options = {}) {
+  const dependencyNames = Object.keys(dependencies ?? {}).sort();
+  const missing = [];
+
+  for (const dependencyName of dependencyNames) {
+    if (!(await hasInstalledPackage(dependencyName, options))) {
+      missing.push(dependencyName);
+    }
+  }
+
+  return missing;
+}
+
+export async function findMissingPackageJsonRuntimeDependencies(packageJsonUrl) {
+  const packageJson = await readPackageJson(packageJsonUrl);
+  const packageRequire = createRequire(packageJsonUrl);
+
+  return findMissingRuntimeDependencies(packageJson.dependencies, {
+    resolvePaths: (dependencyName) => packageRequire.resolve.paths(dependencyName),
+  });
+}
+
+export function formatMissingRuntimeDependenciesMessage(missingDependencies) {
+  const dependencyList = missingDependencies.map((dependencyName) => `  - ${dependencyName}`).join('\n');
+
+  return [
+    'CodeLark build cannot start because package.json runtime dependencies are not installed:',
+    dependencyList,
+    '',
+    'Install dependencies first:',
+    '  npm ci',
+    '',
+    'If you are updating an existing checkout, npm install is also acceptable:',
+    '  npm install',
+    '',
+    'Then rerun:',
+    '  npm run build',
+  ].join('\n');
+}

package/scripts/build.js

@@ -0,0 +1,53 @@
+import {
+  findMissingPackageJsonRuntimeDependencies,
+  formatMissingRuntimeDependenciesMessage,
+} from './build-preflight.js';
+
+const nodeMajor = Number((process.versions.node || '0').split('.')[0]);
+if (!Number.isFinite(nodeMajor) || nodeMajor < 24) {
+  console.error(`CodeLark build requires Node.js 24 or newer. Current Node.js: ${process.version}.`);
+  process.exit(1);
+}
+
+const packageJsonUrl = new URL('../package.json', import.meta.url);
+const missingRuntimeDependencies = await findMissingPackageJsonRuntimeDependencies(packageJsonUrl);
+if (missingRuntimeDependencies.length > 0) {
+  console.error(formatMissingRuntimeDependenciesMessage(missingRuntimeDependencies));
+  process.exit(1);
+}
+
+const esbuild = await import('esbuild');
+
+const common = {
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  target: 'node24',
+  external: [
+    '@openai/codex-sdk',
+    // Keep large IM SDKs external so global/local npm installs resolve them
+    // from node_modules instead of inflating daemon.mjs.
+    '@larksuiteoapi/node-sdk',
+    // ws optional native deps
+    'bufferutil', 'utf-8-validate',
+    // Node.js built-ins
+    'fs', 'path', 'os', 'crypto', 'http', 'https', 'net', 'tls',
+    'stream', 'events', 'url', 'util', 'child_process', 'worker_threads',
+    'node:*',
+  ],
+  banner: { js: "import { createRequire as __codelarkCreateRequire } from 'module'; const require = __codelarkCreateRequire(import.meta.url);" },
+};
+
+async function build(entryPoint, outfile) {
+  await esbuild.build({
+    ...common,
+    entryPoints: [entryPoint],
+    outfile,
+  });
+}
+
+await build('src/entrypoints/daemon.ts', 'dist/daemon.mjs');
+await build('src/operator-ui/server.ts', 'dist/ui-server.mjs');
+await build('src/entrypoints/cli.ts', 'dist/cli.mjs');
+
+console.log('Built dist/daemon.mjs, dist/ui-server.mjs, dist/cli.mjs');

package/scripts/check-npm-pack.js

@@ -0,0 +1,46 @@
+import { spawnSync } from 'node:child_process';
+
+const forbiddenPrefixes = [
+  'package/docs/',
+  'package/docs/.vitepress/',
+];
+
+const forbiddenFiles = new Set([
+  'package/README_EN.md',
+  'package/config.env.example',
+]);
+
+const result = spawnSync('npm', ['pack', '--dry-run', '--json'], {
+  cwd: process.cwd(),
+  encoding: 'utf8',
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+
+if (result.status !== 0) {
+  process.stderr.write(result.stderr);
+  process.exit(result.status ?? 1);
+}
+
+let packEntries;
+try {
+  packEntries = JSON.parse(result.stdout);
+} catch (error) {
+  console.error('Unable to parse npm pack --dry-run --json output.');
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+const files = packEntries.flatMap((entry) => entry.files?.map((file) => file.path) ?? []);
+const forbiddenMatches = files.filter((file) =>
+  forbiddenFiles.has(file) || forbiddenPrefixes.some((prefix) => file.startsWith(prefix)),
+);
+
+if (forbiddenMatches.length > 0) {
+  console.error('Unexpected files would be included in the npm package:');
+  for (const file of forbiddenMatches) {
+    console.error(`- ${file}`);
+  }
+  process.exit(1);
+}
+
+console.log(`npm package dry-run passed: ${files.length} files, no docs or example env files included.`);

package/scripts/daemon.ps1

@@ -0,0 +1,16 @@
+<#
+.SYNOPSIS
+  Windows entry point — delegates to supervisor-windows.ps1.
+.DESCRIPTION
+  Usage:  powershell -File scripts\daemon.ps1 start|stop|status|logs|install-service|uninstall-service
+#>
+param(
+    [Parameter(Position=0)]
+    [string]$Command = 'help',
+
+    [Parameter(Position=1)]
+    [int]$LogLines = 50
+)
+
+$supervisorScript = Join-Path (Split-Path -Parent $PSCommandPath) 'supervisor-windows.ps1'
+& $supervisorScript $Command $LogLines

package/scripts/daemon.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+set -euo pipefail
+CODELARK_HOME="${CODELARK_HOME:-$HOME/.codelark}"
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+PID_FILE="$CODELARK_HOME/runtime/bridge.pid"
+STATUS_FILE="$CODELARK_HOME/runtime/status.json"
+LOG_FILE="$CODELARK_HOME/logs/bridge.log"
+
+# ── Common helpers ──
+
+ensure_dirs() { mkdir -p "$CODELARK_HOME"/{data,logs,runtime,data/messages}; }
+
+ensure_built() {
+  local need_build=0
+  if [ ! -f "$SKILL_DIR/dist/daemon.mjs" ]; then
+    need_build=1
+  else
+    # Check if any source file is newer than the bundle
+    local newest_src
+    newest_src=$(find "$SKILL_DIR/src" -name '*.ts' -newer "$SKILL_DIR/dist/daemon.mjs" 2>/dev/null | head -1)
+    if [ -n "$newest_src" ]; then
+      need_build=1
+    fi
+    # Also check if node_modules/codelark was updated (npm update)
+    # — its code is bundled into dist, so changes require a rebuild
+    if [ "$need_build" = "0" ] && [ -d "$SKILL_DIR/node_modules/codelark/src" ]; then
+      local newest_dep
+      newest_dep=$(find "$SKILL_DIR/node_modules/codelark/src" -name '*.ts' -newer "$SKILL_DIR/dist/daemon.mjs" 2>/dev/null | head -1)
+      if [ -n "$newest_dep" ]; then
+        need_build=1
+      fi
+    fi
+  fi
+  if [ "$need_build" = "1" ]; then
+    echo "Building daemon bundle..."
+    (cd "$SKILL_DIR" && npm run build)
+  fi
+}
+
+# Clean environment for subprocess isolation.
+clean_env() {
+  unset CLAUDECODE 2>/dev/null || true
+
+  local mode="${CODELARK_ENV_ISOLATION:-inherit}"
+  if [ "$mode" = "strict" ]; then
+    while IFS='=' read -r name _; do
+      case "$name" in ANTHROPIC_*) unset "$name" 2>/dev/null || true ;; esac
+    done < <(env)
+  fi
+}
+
+read_pid() {
+  [ -f "$PID_FILE" ] && cat "$PID_FILE" 2>/dev/null || echo ""
+}
+
+pid_alive() {
+  local pid="$1"
+  [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null
+}
+
+status_running() {
+  [ -f "$STATUS_FILE" ] && grep -q '"running"[[:space:]]*:[[:space:]]*true' "$STATUS_FILE" 2>/dev/null
+}
+
+show_last_exit_reason() {
+  if [ -f "$STATUS_FILE" ]; then
+    local reason
+    reason=$(grep -o '"lastExitReason"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATUS_FILE" 2>/dev/null | head -1 | sed 's/.*: *"//;s/"$//')
+    [ -n "$reason" ] && echo "Last exit reason: $reason"
+  fi
+}
+
+show_failure_help() {
+  echo ""
+  echo "Recent logs:"
+  tail -20 "$LOG_FILE" 2>/dev/null || echo "  (no log file)"
+  echo ""
+  echo "Next steps:"
+  echo "  1. Run diagnostics:  bash \"$SKILL_DIR/scripts/doctor.sh\""
+  echo "  2. Check full logs:  bash \"$SKILL_DIR/scripts/daemon.sh\" logs 100"
+  echo "  3. Rebuild bundle:   cd \"$SKILL_DIR\" && npm run build"
+}
+
+# ── Load platform-specific supervisor ──
+
+case "$(uname -s)" in
+  Darwin)
+    # shellcheck source=supervisor-macos.sh
+    source "$SKILL_DIR/scripts/supervisor-macos.sh"
+    ;;
+  MINGW*|MSYS*|CYGWIN*)
+    # Windows detected via Git Bash / MSYS2 / Cygwin — delegate to PowerShell
+    echo "Windows detected. Delegating to supervisor-windows.ps1..."
+    powershell.exe -ExecutionPolicy Bypass -File "$SKILL_DIR/scripts/supervisor-windows.ps1" "$@"
+    exit $?
+    ;;
+  *)
+    # shellcheck source=supervisor-linux.sh
+    source "$SKILL_DIR/scripts/supervisor-linux.sh"
+    ;;
+esac
+
+# ── Commands ──
+
+case "${1:-help}" in
+  start)
+    ensure_dirs
+    ensure_built
+
+    # Check if already running (supervisor-aware: launchctl on macOS, PID on Linux)
+    if supervisor_is_running; then
+      EXISTING_PID=$(read_pid)
+      echo "Bridge already running${EXISTING_PID:+ (PID: $EXISTING_PID)}"
+      cat "$STATUS_FILE" 2>/dev/null
+      exit 1
+    fi
+
+    # Source config.env BEFORE clean_env so CODELARK_* flags are available.
+    [ -f "$CODELARK_HOME/config.env" ] && set -a && source "$CODELARK_HOME/config.env" && set +a
+
+    clean_env
+    echo "Starting bridge..."
+    supervisor_start
+
+    # Poll for up to 10 seconds waiting for status.json to report running
+    STARTED=false
+    for _ in $(seq 1 10); do
+      sleep 1
+      if status_running; then
+        STARTED=true
+        break
+      fi
+      # If supervisor process already died, stop waiting
+      if ! supervisor_is_running; then
+        break
+      fi
+    done
+
+    if [ "$STARTED" = "true" ]; then
+      NEW_PID=$(read_pid)
+      echo "Bridge started${NEW_PID:+ (PID: $NEW_PID)}"
+      cat "$STATUS_FILE" 2>/dev/null
+    else
+      echo "Failed to start bridge."
+      supervisor_is_running || echo "  Process not running."
+      status_running || echo "  status.json not reporting running=true."
+      show_last_exit_reason
+      show_failure_help
+      exit 1
+    fi
+    ;;
+
+  stop)
+    if supervisor_is_managed; then
+      echo "Stopping bridge..."
+      supervisor_stop
+      echo "Bridge stopped"
+    else
+      PID=$(read_pid)
+      if [ -z "$PID" ]; then echo "No bridge running"; exit 0; fi
+      if pid_alive "$PID"; then
+        kill "$PID"
+        for _ in $(seq 1 10); do
+          pid_alive "$PID" || break
+          sleep 1
+        done
+        pid_alive "$PID" && kill -9 "$PID"
+        echo "Bridge stopped"
+      else
+        echo "Bridge was not running (stale PID file)"
+      fi
+      rm -f "$PID_FILE"
+    fi
+    ;;
+
+  status)
+    # Platform-specific status info (prints launchd/service state)
+    supervisor_status_extra
+
+    # Process status: supervisor-aware (launchctl on macOS, PID on Linux)
+    if supervisor_is_running; then
+      PID=$(read_pid)
+      echo "Bridge process is running${PID:+ (PID: $PID)}"
+      # Business status from status.json
+      if status_running; then
+        echo "Bridge status: running"
+      else
+        echo "Bridge status: process alive but status.json not reporting running"
+      fi
+      cat "$STATUS_FILE" 2>/dev/null
+    else
+      echo "Bridge is not running"
+      [ -f "$PID_FILE" ] && rm -f "$PID_FILE"
+      show_last_exit_reason
+    fi
+    ;;
+
+  logs)
+    N="${2:-50}"
+    tail -n "$N" "$LOG_FILE" 2>/dev/null | sed -E 's/(token|secret|password)(["\\x27]?\s*[:=]\s*["\\x27]?)[^ "]+/\1\2*****/gi'
+    ;;
+
+  *)
+    echo "Usage: daemon.sh {start|stop|status|logs [N]}"
+    ;;
+esac

package/scripts/doctor.ps1

@@ -0,0 +1,27 @@
+<#
+.SYNOPSIS
+  Windows wrapper for the existing bash-based doctor script.
+.DESCRIPTION
+  Prefers Git Bash / bash.exe when available. Falls back to a clear message
+  when bash is missing, because the full diagnostics live in doctor.sh.
+#>
+
+$ErrorActionPreference = 'Stop'
+
+$doctorScript = Join-Path (Split-Path -Parent $PSCommandPath) 'doctor.sh'
+
+if (-not (Test-Path $doctorScript)) {
+    Write-Error "doctor.sh not found at $doctorScript"
+    exit 1
+}
+
+$bash = Get-Command bash -ErrorAction SilentlyContinue
+if (-not $bash) {
+    Write-Host "bash was not found in PATH."
+    Write-Host "Install Git Bash or another bash environment, then run:"
+    Write-Host "  bash `"$doctorScript`""
+    exit 1
+}
+
+& $bash.Source $doctorScript
+exit $LASTEXITCODE

package/scripts/doctor.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+set -euo pipefail
+CODELARK_HOME="${CODELARK_HOME:-${CODELARK_HOME:-$HOME/.codelark}}"
+CONFIG_FILE="$CODELARK_HOME/config.env"
+PID_FILE="$CODELARK_HOME/runtime/bridge.pid"
+LOG_FILE="$CODELARK_HOME/logs/bridge.log"
+
+PASS=0
+FAIL=0
+
+check() {
+  local label="$1"
+  local result="$2"
+  if [ "$result" = "0" ]; then
+    echo "[OK]   $label"
+    PASS=$((PASS + 1))
+  else
+    echo "[FAIL] $label"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# --- Node.js version ---
+if command -v node &>/dev/null; then
+  NODE_VER=$(node -v | sed 's/v//' | cut -d. -f1)
+  if [ "$NODE_VER" -ge 20 ] 2>/dev/null; then
+    check "Node.js >= 20 (found v$(node -v | sed 's/v//'))" 0
+  else
+    check "Node.js >= 20 (found v$(node -v | sed 's/v//'), need >= 20)" 1
+  fi
+else
+  check "Node.js installed" 1
+fi
+
+# --- Helper: read a value from config.env ---
+get_config() { grep "^$1=" "$CONFIG_FILE" 2>/dev/null | head -1 | cut -d= -f2- | sed 's/^["'"'"']//;s/["'"'"']$//'; }
+
+# --- Read runtime setting ---
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CODELARK_RUNTIME=$(get_config CODELARK_RUNTIME)
+CODELARK_RUNTIME="codex"
+echo "Runtime: $CODELARK_RUNTIME"
+echo ""
+
+# --- Codex checks ---
+  if command -v codex &>/dev/null; then
+    CODEX_VER=$(codex --version 2>/dev/null || echo "unknown")
+    check "Codex CLI available (${CODEX_VER})" 0
+  else
+    check "Codex CLI available (not found in PATH)" 1
+  fi
+
+  # Check @openai/codex-sdk
+  CODEX_SDK="$SKILL_DIR/node_modules/@openai/codex-sdk"
+  if [ -d "$CODEX_SDK" ]; then
+    check "@openai/codex-sdk installed" 0
+  else
+    check "@openai/codex-sdk installed (not found — run 'npm install' in $SKILL_DIR)" 1
+  fi
+
+  # Check Codex auth: any of CODELARK_CODEX_API_KEY / CODEX_API_KEY / OPENAI_API_KEY,
+  # or `codex auth status` showing logged-in (interactive login).
+  CODEX_AUTH=1
+  if [ -n "${CODELARK_CODEX_API_KEY:-}" ] || [ -n "${CODEX_API_KEY:-}" ] || [ -n "${OPENAI_API_KEY:-}" ]; then
+    CODEX_AUTH=0
+  elif command -v codex &>/dev/null; then
+    CODEX_AUTH_OUT=$(codex auth status 2>&1 || true)
+    if echo "$CODEX_AUTH_OUT" | grep -qiE 'logged.in|authenticated'; then
+      CODEX_AUTH=0
+    fi
+  fi
+  if [ "$CODEX_AUTH" = "0" ]; then
+    check "Codex auth available (API key or login)" 0
+  else
+    check "Codex auth available (set OPENAI_API_KEY or run 'codex auth login')" 1
+  fi
+
+# --- dist/daemon.mjs freshness ---
+DAEMON_MJS="$SKILL_DIR/dist/daemon.mjs"
+if [ -f "$DAEMON_MJS" ]; then
+  STALE_SRC=$(find "$SKILL_DIR/src" -name '*.ts' -newer "$DAEMON_MJS" 2>/dev/null | head -1)
+  if [ -z "$STALE_SRC" ]; then
+    check "dist/daemon.mjs is up to date" 0
+  else
+    check "dist/daemon.mjs is stale (src changed, run 'npm run build')" 1
+  fi
+else
+  check "dist/daemon.mjs exists (not built — run 'npm run build')" 1
+fi
+
+# --- config.env exists ---
+if [ -f "$CONFIG_FILE" ]; then
+  check "config.env exists" 0
+else
+  check "config.env exists ($CONFIG_FILE not found)" 1
+fi
+
+# --- config.env permissions ---
+if [ -f "$CONFIG_FILE" ]; then
+  PERMS=$(stat -f "%Lp" "$CONFIG_FILE" 2>/dev/null || stat -c "%a" "$CONFIG_FILE" 2>/dev/null || echo "unknown")
+  if [ "$PERMS" = "600" ]; then
+    check "config.env permissions are 600" 0
+  else
+    check "config.env permissions are 600 (currently $PERMS)" 1
+  fi
+fi
+
+# --- Load config for channel checks ---
+if [ -f "$CONFIG_FILE" ]; then
+  CODELARK_CHANNELS=$(get_config CODELARK_ENABLED_CHANNELS)
+
+  # --- Feishu ---
+  if echo "$CODELARK_CHANNELS" | grep -q feishu; then
+    FS_APP_ID=$(get_config CODELARK_FEISHU_APP_ID)
+    FS_SECRET=$(get_config CODELARK_FEISHU_APP_SECRET)
+    FS_SITE=$(get_config CODELARK_FEISHU_SITE)
+    case "$FS_SITE" in
+      lark|*open.larksuite.com*)
+        FS_DOMAIN="https://open.larksuite.com"
+        ;;
+      *)
+        FS_DOMAIN="https://open.feishu.cn"
+        ;;
+    esac
+    if [ -n "$FS_APP_ID" ] && [ -n "$FS_SECRET" ]; then
+      FEISHU_RESULT=$(curl -s --max-time 5 -X POST "${FS_DOMAIN}/open-apis/auth/v3/tenant_access_token/internal" \
+        -H "Content-Type: application/json" \
+        -d "{\"app_id\":\"${FS_APP_ID}\",\"app_secret\":\"${FS_SECRET}\"}" 2>/dev/null || echo '{"code":1}')
+      if echo "$FEISHU_RESULT" | grep -q '"code"[[:space:]]*:[[:space:]]*0'; then
+        check "Feishu app credentials are valid" 0
+      else
+        check "Feishu app credentials are valid (token request failed)" 1
+      fi
+    else
+      check "Feishu app credentials configured" 1
+    fi
+  fi
+
+fi
+
+# --- Log directory writable ---
+LOG_DIR="$CODELARK_HOME/logs"
+if [ -d "$LOG_DIR" ] && [ -w "$LOG_DIR" ]; then
+  check "Log directory is writable" 0
+else
+  check "Log directory is writable ($LOG_DIR)" 1
+fi
+
+# --- PID file consistency ---
+if [ -f "$PID_FILE" ]; then
+  PID=$(cat "$PID_FILE")
+  if kill -0 "$PID" 2>/dev/null; then
+    check "PID file consistent (process $PID is running)" 0
+  else
+    check "PID file consistent (stale PID $PID, process not running)" 1
+  fi
+else
+  check "PID file consistency (no PID file, OK)" 0
+fi
+
+# --- Recent errors in log ---
+if [ -f "$LOG_FILE" ]; then
+  ERROR_COUNT=$(tail -50 "$LOG_FILE" | grep -ciE 'ERROR|Fatal' || true)
+  if [ "$ERROR_COUNT" -eq 0 ]; then
+    check "No recent errors in log (last 50 lines)" 0
+  else
+    check "No recent errors in log (found $ERROR_COUNT ERROR/Fatal lines)" 1
+  fi
+else
+  check "Log file exists (not yet created)" 0
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo ""
+  echo "Common fixes:"
+  echo "  SDK cli.js missing    → cd $SKILL_DIR && npm install"
+  echo "  dist/daemon.mjs stale → cd $SKILL_DIR && npm run build"
+  echo "  config.env missing    → run setup wizard"
+  echo "  Stale PID file        → run stop, then start"
+fi
+
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1