@kontextmind/kxm 0.7.0 → 0.7.4

package/plugins/kxm/src/completion-install.ts

@@ -0,0 +1,223 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { generateShellCompletion, type SupportedShell } from "./autocomplete.ts";
+
+export const COMPLETION_MARKER = "# kxm completion";
+export const PATH_MARKER = "# kxm path";
+export interface CompletionInstallOptions {
+  env?: NodeJS.ProcessEnv | undefined;
+  homeDir?: string | undefined;
+  configDir?: string | undefined;
+  platform?: NodeJS.Platform | undefined;
+  isTty?: boolean | undefined;
+  shell?: string | undefined;
+  dryRun?: boolean | undefined;
+  overwrite?: boolean | undefined;
+}
+
+export interface CompletionInstallReport {
+  ok: boolean;
+  shell: SupportedShell | "unknown";
+  scriptPath: string;
+  rcFile: string | undefined;
+  rcModified: boolean;
+  alreadyInstalled: boolean;
+  reason?: string | undefined;
+}
+
+export function detectShell(env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform): SupportedShell | "unknown" {
+  const shellPath = env.SHELL?.trim() || (process.platform === "win32" ? undefined : env.SHELL?.trim());
+  const name = shellPath ? basename(shellPath).toLowerCase() : "";
+  if (name === "bash" || name === "zsh" || name === "fish") return name;
+  if (name.endsWith("bash") || name.includes("bash")) return "bash";
+  if (name.endsWith("zsh")) return "zsh";
+  if (name.endsWith("fish")) return "fish";
+  return "unknown";
+}
+
+function effectiveHome(options: Pick<CompletionInstallOptions, "env" | "homeDir">): string {
+  const env = options.env ?? process.env;
+  if (options.homeDir) return options.homeDir;
+  const envHome = env.HOME?.trim() ?? env.USERPROFILE?.trim();
+  return envHome && envHome.length > 0 ? resolve(envHome) : homedir();
+}
+
+export function completionScriptPath(shell: SupportedShell, options: Pick<CompletionInstallOptions, "env" | "homeDir" | "configDir"> = {}): string {
+  const env = options.env ?? process.env;
+  const explicit = options.configDir ?? env.KXM_USER_CONFIG_DIR?.trim();
+  const base = explicit && explicit.length > 0 ? resolve(explicit) : resolve(effectiveHome(options), ".config", "kxm");
+  return join(base, "completions", `kxm.${shell}`);
+}
+
+function bashRcCandidate(options: Pick<CompletionInstallOptions, "env" | "homeDir">): string | undefined {
+  const home = effectiveHome(options);
+  const candidates = [join(home, ".bashrc"), join(home, ".bash_profile")];
+  const existing = candidates.find((candidate) => existsSync(candidate));
+  return existing ?? candidates[0];
+}
+
+function zshRcCandidate(options: Pick<CompletionInstallOptions, "env" | "homeDir">): string | undefined {
+  const env = options.env ?? process.env;
+  const home = effectiveHome(options);
+  if (env.ZDOTDIR?.trim()) return join(resolve(env.ZDOTDIR.trim()), ".zshrc");
+  return join(home, ".zshrc");
+}
+
+function fishCompletionTarget(shell: SupportedShell, options: Pick<CompletionInstallOptions, "env" | "homeDir">): string {
+  const env = options.env ?? process.env;
+  const home = effectiveHome(options);
+  if (env.XDG_CONFIG_HOME?.trim()) return join(resolve(env.XDG_CONFIG_HOME.trim()), "fish", "completions", "kxm.fish");
+  return join(home, ".config", "fish", "completions", "kxm.fish");
+}
+
+export function completionRcTarget(shell: SupportedShell, options: Pick<CompletionInstallOptions, "env" | "homeDir"> = {}): { rcFile?: string | undefined } {
+  if (shell === "fish") {
+    return { rcFile: undefined }; // fish auto-loads ~/.config/fish/completions
+  }
+  if (shell === "zsh") {
+    return { rcFile: zshRcCandidate(options) };
+  }
+  return { rcFile: bashRcCandidate(options) };
+}
+
+function sourceLine(shell: SupportedShell, scriptPath: string): string {
+  if (shell === "fish") return `source ${scriptPath}`;
+  if (shell === "zsh") return `[[ -f ${scriptPath} ]] && source ${scriptPath}`;
+  return `[[ -f ${scriptPath} ]] && source ${scriptPath}`;
+}
+
+export function installShellCompletion(
+  shellInput: string | undefined,
+  options: CompletionInstallOptions = {},
+): CompletionInstallReport {
+  const shell = shellInput?.trim() && shellInput !== "auto" ? shellInput.trim() as SupportedShell : detectShell(options.env ?? process.env, options.platform ?? process.platform);
+  if (shell !== "bash" && shell !== "zsh" && shell !== "fish") {
+    return {
+      ok: false,
+      shell: "unknown",
+      scriptPath: "",
+      rcFile: undefined,
+      rcModified: false,
+      alreadyInstalled: false,
+      reason: "shell_not_detected",
+    };
+  }
+
+  const scriptPath = completionScriptPath(shell, options);
+  const { rcFile } = completionRcTarget(shell, options);
+  const script = generateShellCompletion(shell);
+
+  const existingScript = existsSync(scriptPath);
+  const existingScriptMatches = existingScript && readFileSync(scriptPath, "utf8") === script;
+
+  let rcModified = false;
+  let alreadyInstalled = false;
+
+  if (shell === "fish") {
+    // fish auto-loads files in ~/.config/fish/completions by filename; no rc edit needed
+    const fishTarget = fishCompletionTarget(shell, options);
+    const fishInstalled = existsSync(fishTarget) && readFileSync(fishTarget, "utf8") === script;
+    alreadyInstalled = fishInstalled;
+    if (!options.dryRun && (!fishInstalled || options.overwrite)) {
+      mkdirSync(resolve(fishTarget, ".."), { recursive: true });
+      writeFileSync(fishTarget, script, { encoding: "utf8" });
+    }
+    return {
+      ok: true,
+      shell,
+      scriptPath: fishTarget,
+      rcFile: undefined,
+      rcModified: !fishInstalled,
+      alreadyInstalled,
+    };
+  }
+
+  if (rcFile) {
+    const line = sourceLine(shell, scriptPath);
+    const rcContent = existsSync(rcFile) ? readFileSync(rcFile, "utf8") : "";
+    alreadyInstalled = rcContent.includes(line) || rcContent.includes(`${COMPLETION_MARKER}`);
+  }
+
+  if (!options.dryRun) {
+    if (!existingScriptMatches || options.overwrite) {
+      mkdirSync(resolve(scriptPath, ".."), { recursive: true });
+      writeFileSync(scriptPath, script, { encoding: "utf8" });
+    }
+    if (rcFile && !alreadyInstalled) {
+      const line = sourceLine(shell, scriptPath);
+      const marker = `${COMPLETION_MARKER} (${new Date().toISOString()})`;
+      const stanza = `\n${marker}\n${line}\n`;
+      mkdirSync(resolve(rcFile, ".."), { recursive: true });
+      writeFileSync(rcFile, (existsSync(rcFile) ? readFileSync(rcFile, "utf8") : "") + stanza, { encoding: "utf8" });
+      rcModified = true;
+    }
+  }
+
+  return {
+    ok: true,
+    shell,
+    scriptPath,
+    rcFile,
+    rcModified,
+    alreadyInstalled,
+  };
+}
+
+export interface PathInstallReport {
+  ok: boolean;
+  binDir: string | undefined;
+  rcFile: string | undefined;
+  rcModified: boolean;
+  alreadyInstalled: boolean;
+  reason?: string | undefined;
+}
+
+/** Locate the directory containing the kxm entrypoint (global npm bin or clone scripts dir). */
+export function kxmBinDir(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const argv1 = env.KXM_ENTRY ?? process.argv[1];
+  if (argv1 && isAbsolute(argv1)) {
+    const dir = dirname(argv1);
+    if (existsSync(join(dir, process.platform === "win32" ? "kxm.cmd" : "kxm"))) return dir;
+  }
+  // fall back to PATH lookup
+  const pathEnv = env.PATH ?? "";
+  for (const part of pathEnv.split(delimiter)) {
+    if (!part) continue;
+    const candidate = resolve(part, process.platform === "win32" ? "kxm.cmd" : "kxm");
+    if (existsSync(candidate)) return resolve(part);
+  }
+  return undefined;
+}
+
+export function kxmOnPath(env: NodeJS.ProcessEnv = process.env): boolean {
+  return kxmBinDir(env) !== undefined;
+}
+
+function pathLine(binDir: string): string {
+  return `export PATH="${binDir}:$PATH" # kxm`;
+}
+
+/** Append a PATH export for the kxm bin dir to the shell rc (bash/zsh). */
+export function installPathEntry(
+  shellInput: string | undefined,
+  options: CompletionInstallOptions & { binDir?: string } = {},
+): PathInstallReport {
+  const shell = shellInput?.trim() && shellInput !== "auto" ? shellInput.trim() as SupportedShell : detectShell(options.env ?? process.env, options.platform ?? process.platform);
+  if (shell !== "bash" && shell !== "zsh") {
+    return { ok: false, binDir: undefined, rcFile: undefined, rcModified: false, alreadyInstalled: false, reason: "shell_not_supported" };
+  }
+  const binDir = options.binDir ?? kxmBinDir(options.env ?? process.env);
+  if (!binDir) {
+    return { ok: false, binDir: undefined, rcFile: undefined, rcModified: false, alreadyInstalled: false, reason: "kxm_not_found" };
+  }
+  const { rcFile } = completionRcTarget(shell, options);
+  const line = pathLine(binDir);
+  const rcContent = existsSync(rcFile ?? "") ? readFileSync(rcFile!, "utf8") : "";
+  const alreadyInstalled = rcContent.includes(binDir) || (options.env?.PATH ?? process.env.PATH ?? "").split(delimiter).includes(binDir);
+  if (!options.dryRun && rcFile && !alreadyInstalled) {
+    mkdirSync(dirname(rcFile), { recursive: true });
+    writeFileSync(rcFile, rcContent + `\n${PATH_MARKER}\n${line}\n`, { encoding: "utf8" });
+  }
+  return { ok: true, binDir, rcFile, rcModified: !alreadyInstalled && !options.dryRun, alreadyInstalled };
+}

package/plugins/kxm/src/database.ts

@@ -11,7 +11,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { DatabaseSync } from "./sqlite.ts";
 import { VnextConfigError, type VnextConfigIssue } from "./vnext-config.ts";
 
 export interface DatabaseMigrationStep {

package/plugins/kxm/src/external-effects.ts

@@ -3,7 +3,7 @@
  * Ensures deterministic branching, preflight CAS checks, and immutable receipts for external mutations.
  */
 
-import { DatabaseSync } from "node:sqlite";
+import { DatabaseSync } from "./sqlite.ts";
 import { createHash } from "node:crypto";
 import {
   mkdirSync,

package/plugins/kxm/src/hub-env.ts

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+export const HUB_ENV_SCHEMA = "kxm.hub-env.v1" as const;
+
+export interface HubEnvRecord {
+  schema: typeof HUB_ENV_SCHEMA;
+  /** ISO-8601 creation time of the persisted record. */
+  createdAt: string;
+  authToken?: string | undefined;
+  projectTokens?: Record<string, string> | undefined;
+}
+
+export class HubEnvError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "HubEnvError";
+  }
+}
+
+function resolveUserStateRoot(env: NodeJS.ProcessEnv): string {
+  const explicit = env.KXM_STATE_HOME?.trim();
+  if (explicit) {
+    if (!isAbsolute(explicit)) throw new HubEnvError("local_state_root_not_absolute");
+    return resolve(explicit);
+  }
+  if (process.platform === "win32") {
+    const localAppData = env.LOCALAPPDATA?.trim();
+    const base = localAppData && isAbsolute(localAppData) ? localAppData : join(homedir(), "AppData", "Local");
+    return resolve(base, "KXM");
+  }
+  if (process.platform === "darwin") return resolve(homedir(), "Library", "Application Support", "KXM");
+  const xdgState = env.XDG_STATE_HOME?.trim();
+  const base = xdgState && isAbsolute(xdgState) ? xdgState : join(homedir(), ".local", "state");
+  return resolve(base, "kxm");
+}
+
+export function hubEnvFile(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveUserStateRoot(env), "hub-env.json");
+}
+
+export function generateHubAuthToken(): string {
+  return `kxm_admin_${randomBytes(24).toString("base64url")}`;
+}
+
+export function readHubEnvRecord(env: NodeJS.ProcessEnv = process.env): HubEnvRecord | undefined {
+  const file = hubEnvFile(env);
+  if (!existsSync(file)) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new HubEnvError(`hub env file is malformed at ${file}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new HubEnvError(`hub env file is malformed at ${file}: expected a JSON object`);
+  }
+  const record = parsed as Partial<HubEnvRecord>;
+  if (record.schema !== HUB_ENV_SCHEMA) {
+    throw new HubEnvError(`hub env file at ${file} has unsupported schema ${String(record.schema)}`);
+  }
+  if (record.authToken !== undefined && (typeof record.authToken !== "string" || record.authToken.trim().length === 0)) {
+    throw new HubEnvError(`hub env file at ${file} has an invalid authToken`);
+  }
+  if (record.projectTokens !== undefined) {
+    const tokens = record.projectTokens;
+    if (!tokens || typeof tokens !== "object" || Array.isArray(tokens)) {
+      throw new HubEnvError(`hub env file at ${file} has invalid projectTokens`);
+    }
+    for (const [project, token] of Object.entries(tokens)) {
+      if (!project.trim() || typeof token !== "string" || !token.trim()) {
+        throw new HubEnvError(`hub env file at ${file} has an empty project name or token`);
+      }
+    }
+  }
+  return {
+    schema: HUB_ENV_SCHEMA,
+    createdAt: typeof record.createdAt === "string" ? record.createdAt : "",
+    ...(record.authToken !== undefined ? { authToken: record.authToken } : {}),
+    ...(record.projectTokens !== undefined ? { projectTokens: record.projectTokens } : {}),
+  };
+}
+
+export function writeHubEnvRecord(record: HubEnvRecord, env: NodeJS.ProcessEnv = process.env): string {
+  const file = hubEnvFile(env);
+  const directory = dirname(file);
+  mkdirSync(directory, { recursive: true });
+  const temporary = join(directory, `.hub-env-${process.pid}.tmp`);
+  writeFileSync(temporary, `${JSON.stringify(record, undefined, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  try {
+    renameSync(temporary, file);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
+  return file;
+}
+
+export interface ResolveHubCredentialsOptions {
+  env?: NodeJS.ProcessEnv | undefined;
+  /** Injectable token generator for tests. */
+  generateToken?: () => string | undefined;
+  /** When false, never create or update the persisted file. */
+  persist?: boolean | undefined;
+  now?: () => string | undefined;
+}
+
+export interface ResolvedHubCredentials {
+  authToken: string | undefined;
+  projectTokens: Record<string, string> | undefined;
+  /** Where each value came from; `generated` values were persisted when allowed. */
+  authTokenSource: "env" | "file" | "generated" | "none";
+  projectTokensSource: "env" | "file" | "generated" | "none";
+  envFile: string | undefined;
+  written: boolean;
+}
+
+function parseProjectTokens(raw: string | undefined): Record<string, string> | undefined | "invalid" {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return "invalid";
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return "invalid";
+  const entries = Object.entries(parsed as Record<string, unknown>);
+  if (entries.some(([project, token]) => !project.trim() || typeof token !== "string" || !token.trim())) return "invalid";
+  return Object.fromEntries(entries) as Record<string, string>;
+}
+
+/** Resolve hub credentials with persistence across restarts.
+ *
+ * Precedence: explicit environment variable, then the persisted user-state
+ * file, then (for the admin token only) a freshly generated token that is
+ * persisted so later restarts and workers reuse the same credential. */
+export function resolveHubCredentials(options: ResolveHubCredentialsOptions = {}): ResolvedHubCredentials {
+  const env = options.env ?? process.env;
+  const persist = options.persist !== false;
+  const existing = readHubEnvRecord(env);
+  const envFile = hubEnvFile(env);
+
+  const envAuthToken = env.KXM_AUTH_TOKEN?.trim();
+  const envProjectTokens = parseProjectTokens(env.KXM_PROJECT_TOKENS);
+  if (envProjectTokens === "invalid") {
+    throw new HubEnvError("KXM_PROJECT_TOKENS must be a JSON object of project names to tokens");
+  }
+
+  let authTokenSource: ResolvedHubCredentials["authTokenSource"] = "none";
+  let authToken = envAuthToken || existing?.authToken;
+  if (envAuthToken) authTokenSource = "env";
+  else if (authToken) authTokenSource = "file";
+
+  if (!authToken) {
+    const generated = options.generateToken?.() ?? generateHubAuthToken();
+    if (generated) {
+      authToken = generated;
+      authTokenSource = "generated";
+    }
+  }
+
+  let projectTokensSource: ResolvedHubCredentials["projectTokensSource"] = "none";
+  let projectTokens = envProjectTokens ?? existing?.projectTokens;
+  if (envProjectTokens) projectTokensSource = "env";
+  else if (projectTokens) projectTokensSource = "file";
+
+  const needsPersist = persist
+    && (authTokenSource === "generated"
+      || (authTokenSource === "env" && existing?.authToken !== authToken)
+      || (projectTokensSource === "env" && JSON.stringify(existing?.projectTokens ?? undefined) !== JSON.stringify(projectTokens ?? undefined)));
+
+  if (needsPersist) {
+    const record: HubEnvRecord = {
+      schema: HUB_ENV_SCHEMA,
+      createdAt: existing?.createdAt || (options.now?.() ?? new Date().toISOString()),
+      ...(authToken ? { authToken } : {}),
+      ...(projectTokens ? { projectTokens } : {}),
+    };
+    writeHubEnvRecord(record, env);
+  }
+
+  return {
+    authToken,
+    projectTokens,
+    authTokenSource,
+    projectTokensSource,
+    envFile: needsPersist || existing ? envFile : undefined,
+    written: needsPersist === true,
+  };
+}