@wkronmiller/lisa 0.1.0

package/src/harness/command.ts

@@ -0,0 +1,173 @@
+import { existsSync, statSync } from "fs";
+import { isAbsolute, resolve } from "path";
+
+import type { HarnessAvailability, HarnessRequest, HarnessResult } from "./types";
+
+const IS_WINDOWS = process.platform === "win32";
+const LISA_ABORT_PREFIX = "LISA_ABORT:";
+const LISA_ABORT_START = "LISA_ABORT_START";
+const LISA_ABORT_END = "LISA_ABORT_END";
+
+function looksLikePathCommand(command: string): boolean {
+  return command.includes("/") || command.includes("\\");
+}
+
+export function resolveHarnessCommandOverride(command: string, workspaceRoot: string): string {
+  return !isAbsolute(command) && looksLikePathCommand(command) ? resolve(workspaceRoot, command) : command;
+}
+
+function resolveConfiguredCommand(envVarNames: string[]): string | undefined {
+  for (const envVar of envVarNames) {
+    const value = process.env[envVar]?.trim();
+    if (value) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+export function resolveConfiguredCommandAvailability(command: string, cwd = process.cwd()): HarnessAvailability {
+  const pathCandidate = !isAbsolute(command) && looksLikePathCommand(command) ? resolve(cwd, command) : command;
+  if (existsSync(pathCandidate)) {
+    const stats = statSync(pathCandidate);
+    const isExecutableFile = stats.isFile() && (IS_WINDOWS || (stats.mode & 0o111) !== 0);
+    if (!isExecutableFile) {
+      return {
+        available: false,
+        reason: `Configured harness command \`${command}\` is not an executable file.`,
+      };
+    }
+
+    return {
+      available: true,
+      command: pathCandidate,
+      reason: "Configured harness command found via environment override.",
+    };
+  }
+
+  const resolved = IS_WINDOWS ? resolveWindowsCommand(command) : Bun.which(command);
+  if (resolved) {
+    return {
+      available: true,
+      command: resolved,
+      reason: "Configured harness command found via environment override.",
+    };
+  }
+
+  return {
+    available: false,
+    reason: `Configured harness command \`${command}\` was not found.`,
+  };
+}
+
+export function detectExplicitHarnessCommand(command: string, cwd = process.cwd()): HarnessAvailability {
+  return resolveConfiguredCommandAvailability(command, cwd);
+}
+
+function resolveWindowsCommand(command: string): string | undefined {
+  const direct = Bun.which(command);
+  if (direct) {
+    return direct;
+  }
+
+  if (!command.toLowerCase().endsWith(".cmd")) {
+    return Bun.which(`${command}.cmd`) ?? undefined;
+  }
+
+  return undefined;
+}
+
+export function resolveHarnessCommand(command: string, envVarNames: string[] = []): string | undefined {
+  const configured = resolveConfiguredCommand(envVarNames);
+  if (configured) {
+    return configured;
+  }
+
+  if (IS_WINDOWS) {
+    return resolveWindowsCommand(command) ?? command;
+  }
+
+  return Bun.which(command) ?? command;
+}
+
+export function detectHarnessCommand(
+  command: string,
+  envVarNames: string[] = [],
+): HarnessAvailability {
+  const configured = resolveConfiguredCommand(envVarNames);
+  if (configured) {
+    return resolveConfiguredCommandAvailability(configured);
+  }
+
+  const resolved = IS_WINDOWS ? resolveWindowsCommand(command) : Bun.which(command);
+  if (resolved) {
+    return {
+      available: true,
+      command: resolved,
+      reason: "Harness CLI detected in PATH.",
+    };
+  }
+
+  return {
+    available: false,
+    reason: `Command \`${command}\` was not found in PATH.`,
+  };
+}
+
+function decodeOutput(output: Uint8Array | null | undefined): string {
+  if (!output) {
+    return "";
+  }
+
+  return new TextDecoder().decode(output);
+}
+
+function extractAbortReason(output: string): string | undefined {
+  const trimmed = output.trim();
+  const blockMatch = trimmed.match(/(?:^|\n)LISA_ABORT_START\s*([\s\S]*?)\s*LISA_ABORT_END(?:\n|$)/);
+  if (blockMatch?.[1]) {
+    return blockMatch[1].trim() || undefined;
+  }
+
+  const nonEmptyLines = trimmed.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  const lastLine = nonEmptyLines[nonEmptyLines.length - 1];
+  if (lastLine?.startsWith(LISA_ABORT_PREFIX)) {
+    return lastLine.slice(LISA_ABORT_PREFIX.length).trim() || "Harness blocked without a reason.";
+  }
+
+  return undefined;
+}
+
+export function runHarnessCommand(command: string, args: string[], request: HarnessRequest): HarnessResult {
+  const proc = Bun.spawnSync({
+    cmd: [command, ...args],
+    cwd: request.cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      ...process.env,
+      ...request.env,
+    },
+    timeout: request.limits?.timeoutSeconds ? request.limits.timeoutSeconds * 1000 : undefined,
+  });
+
+  const stdout = decodeOutput(proc.stdout);
+  const stderr = decodeOutput(proc.stderr);
+  const combined = [stdout.trim(), stderr.trim()].filter((entry) => entry.length > 0).join("\n\n");
+  const abortReason = extractAbortReason(combined);
+
+  return {
+    status: abortReason ? "blocked" : proc.exitCode === 0 ? "success" : "failed",
+    finalText: abortReason ?? combined,
+    abortReason,
+    rawEvents: [
+      {
+        command: [command, ...args],
+        exitCode: proc.exitCode,
+        stdout,
+        stderr,
+      },
+    ],
+  };
+}

package/src/harness/gemini.ts

@@ -0,0 +1,74 @@
+import { resolveGeminiHome } from "../skill/artifacts";
+import { createBaseAdapterHelpers } from "./base-adapter";
+import { resolveHarnessCommand, runHarnessCommand } from "./command";
+import type {
+  HarnessAdapter,
+  HarnessCapabilities,
+  HarnessRequest,
+  HarnessResult,
+  Stage,
+} from "./types";
+
+const SUPPORTED_STAGES: Stage[] = ["generate", "implement", "check", "import"];
+const GEMINI_ENV_VARS = ["LISA_GEMINI_BINARY", "RALPH_GEMINI_BINARY"];
+
+function getGeminiCapabilities(): HarnessCapabilities {
+  return {
+    canEditFiles: true,
+    canResumeSessions: false,
+    supportsStructuredOutput: false,
+    supportsStreaming: false,
+    supportsModelSelection: true,
+    supportsReadOnlyMode: true,
+  };
+}
+
+function buildGeminiArgs(request: HarnessRequest): string[] {
+  const args: string[] = ["--approval-mode", request.allowEdits ? "yolo" : "plan"];
+
+  if (request.model) {
+    args.push("-m", request.model);
+  }
+
+  if (request.extraArgs?.length) {
+    args.push(...request.extraArgs);
+  }
+
+  args.push("-p", request.prompt);
+  return args;
+}
+
+export function createGeminiHarnessAdapter(cwd = process.cwd()): HarnessAdapter {
+  const baseHelpers = createBaseAdapterHelpers(
+    {
+      harnessId: "gemini",
+      commandName: "gemini",
+      envVars: GEMINI_ENV_VARS,
+      artifactName: "GEMINI.md",
+      resolveGlobalRoot: () => resolveGeminiHome(),
+    },
+    cwd
+  );
+
+  return {
+    id: "gemini",
+    displayName: "Gemini CLI",
+    description: "Direct adapter for the Google Gemini CLI.",
+    supportedStages: SUPPORTED_STAGES,
+    ...baseHelpers,
+    async capabilities(): Promise<HarnessCapabilities> {
+      return getGeminiCapabilities();
+    },
+    async run(request: HarnessRequest): Promise<HarnessResult> {
+      const command = request.env?.LISA_HARNESS_COMMAND ?? resolveHarnessCommand("gemini", GEMINI_ENV_VARS);
+      if (!command) {
+        return {
+          status: "failed",
+          finalText: "Gemini CLI not found.",
+        };
+      }
+
+      return runHarnessCommand(command, buildGeminiArgs(request), request);
+    },
+  };
+}

package/src/harness/opencode.ts

@@ -0,0 +1,84 @@
+import { join } from "path";
+
+import { renderOpenCodeSkill, resolveLocalSkillWorkspace, resolveXdgConfigHome } from "../skill/artifacts";
+import { createBaseAdapterHelpers } from "./base-adapter";
+import { resolveHarnessCommand, runHarnessCommand } from "./command";
+import type {
+  HarnessAdapter,
+  HarnessCapabilities,
+  HarnessRequest,
+  HarnessResult,
+  Stage,
+} from "./types";
+
+const SUPPORTED_STAGES: Stage[] = ["generate", "implement", "check", "import"];
+const OPENCODE_ENV_VARS = ["LISA_OPENCODE_BINARY", "RALPH_OPENCODE_BINARY"];
+
+function getOpenCodeCapabilities(): HarnessCapabilities {
+  return {
+    canEditFiles: true,
+    canResumeSessions: false,
+    supportsStructuredOutput: false,
+    supportsStreaming: false,
+    supportsModelSelection: true,
+    supportsReadOnlyMode: false,
+  };
+}
+
+function buildOpenCodeArgs(request: HarnessRequest): string[] {
+  const args = ["run"];
+
+  if (request.model) {
+    args.push("-m", request.model);
+  }
+
+  for (const contextFile of request.contextFiles ?? []) {
+    args.push("--file", contextFile);
+  }
+
+  if (request.extraArgs?.length) {
+    args.push(...request.extraArgs);
+  }
+
+  args.push("--");
+  args.push(request.prompt);
+  return args;
+}
+
+export function createOpenCodeHarnessAdapter(cwd = process.cwd()): HarnessAdapter {
+  const baseHelpers = createBaseAdapterHelpers(
+    {
+      harnessId: "opencode",
+      commandName: "opencode",
+      envVars: OPENCODE_ENV_VARS,
+      artifactName: "AGENTS.md",
+      resolveGlobalRoot: () => join(resolveXdgConfigHome(), "opencode", "skills", "lisa"),
+      resolveGlobalDestination: () => join(resolveXdgConfigHome(), "opencode", "skills", "lisa", "SKILL.md"),
+      resolveLocalDestination: (workspaceDir) => join(resolveLocalSkillWorkspace(workspaceDir), ".opencode", "skills", "lisa", "SKILL.md"),
+      renderContent: renderOpenCodeSkill,
+    },
+    cwd
+  );
+
+  return {
+    id: "opencode",
+    displayName: "OpenCode",
+    description: "Direct adapter for the OpenCode CLI.",
+    supportedStages: SUPPORTED_STAGES,
+    ...baseHelpers,
+    async capabilities(): Promise<HarnessCapabilities> {
+      return getOpenCodeCapabilities();
+    },
+    async run(request: HarnessRequest): Promise<HarnessResult> {
+      const command = request.env?.LISA_HARNESS_COMMAND ?? resolveHarnessCommand("opencode", OPENCODE_ENV_VARS);
+      if (!command) {
+        return {
+          status: "failed",
+          finalText: "OpenCode CLI not found.",
+        };
+      }
+
+      return runHarnessCommand(command, buildOpenCodeArgs(request), request);
+    },
+  };
+}

package/src/harness/registry.ts

@@ -0,0 +1,29 @@
+import { createClaudeCodeHarnessAdapter } from "./claude-code";
+import { createCodexHarnessAdapter } from "./codex";
+import { createGeminiHarnessAdapter } from "./gemini";
+import { createOpenCodeHarnessAdapter } from "./opencode";
+import type { HarnessAdapter, HarnessInspection } from "./types";
+
+export function getHarnessAdapters(cwd = process.cwd()): HarnessAdapter[] {
+  return [
+    createCodexHarnessAdapter(cwd),
+    createOpenCodeHarnessAdapter(cwd),
+    createClaudeCodeHarnessAdapter(cwd),
+    createGeminiHarnessAdapter(cwd),
+  ];
+}
+
+export function getHarnessAdapterById(id: string, cwd = process.cwd()): HarnessAdapter | undefined {
+  return getHarnessAdapters(cwd).find((adapter) => adapter.id === id);
+}
+
+export async function inspectHarnesses(cwd = process.cwd()): Promise<HarnessInspection[]> {
+  const adapters = getHarnessAdapters(cwd);
+  return Promise.all(
+    adapters.map(async (adapter) => ({
+      adapter,
+      availability: await adapter.detect(),
+      capabilities: await adapter.capabilities(),
+    })),
+  );
+}

package/src/harness/runner.ts

@@ -0,0 +1,19 @@
+import { getHarnessAdapterById } from "./registry";
+import { detectExplicitHarnessCommand } from "./command";
+import type { HarnessRequest, HarnessResult } from "./types";
+
+export async function runHarnessStage(harnessId: string, request: HarnessRequest, cwd = process.cwd()): Promise<HarnessResult> {
+  const adapter = getHarnessAdapterById(harnessId, cwd);
+  if (!adapter) {
+    throw new Error(`No harness adapter is registered for \`${harnessId}\`.`);
+  }
+
+  const availability = request.env?.LISA_HARNESS_COMMAND
+    ? detectExplicitHarnessCommand(request.env.LISA_HARNESS_COMMAND, cwd)
+    : await adapter.detect();
+  if (!availability.available) {
+    throw new Error(`Harness \`${harnessId}\` is unavailable: ${availability.reason}`);
+  }
+
+  return adapter.run(request);
+}

package/src/harness/types.ts

@@ -0,0 +1,73 @@
+export type Stage = "generate" | "implement" | "check" | "import";
+export type SkillInstallScope = "global" | "local";
+
+export interface HarnessRequest {
+  stage: Stage;
+  prompt: string;
+  cwd: string;
+  allowEdits: boolean;
+  contextFiles?: string[];
+  model?: string;
+  profile?: string;
+  outputSchema?: unknown;
+  extraArgs?: string[];
+  env?: Record<string, string>;
+  limits?: {
+    maxTurns?: number;
+    timeoutSeconds?: number;
+  };
+}
+
+export interface HarnessResult {
+  status: "success" | "failed" | "needs_input" | "blocked";
+  finalText?: string;
+  structuredOutput?: unknown;
+  sessionId?: string;
+  changedFiles?: string[];
+  abortReason?: string;
+  rawEvents?: unknown[];
+}
+
+export interface HarnessCapabilities {
+  canEditFiles: boolean;
+  canResumeSessions: boolean;
+  supportsStructuredOutput: boolean;
+  supportsStreaming: boolean;
+  supportsModelSelection: boolean;
+  supportsReadOnlyMode: boolean;
+}
+
+export interface HarnessAvailability {
+  available: boolean;
+  command?: string;
+  reason: string;
+}
+
+export interface HarnessSkillInstallDefinition {
+  scope: SkillInstallScope;
+  sourcePath: string;
+  destinationPath: string;
+}
+
+export interface HarnessSkillInstallResult extends HarnessSkillInstallDefinition {
+  status: "created" | "updated" | "unchanged";
+}
+
+export interface HarnessAdapter {
+  id: string;
+  displayName: string;
+  description: string;
+  supportedStages: Stage[];
+  detect(): Promise<HarnessAvailability>;
+  capabilities(): Promise<HarnessCapabilities>;
+  run(request: HarnessRequest): Promise<HarnessResult>;
+  getSkillInstallDefinition?(scope: SkillInstallScope): Promise<HarnessSkillInstallDefinition>;
+  installSkill?(scope: SkillInstallScope): Promise<HarnessSkillInstallResult>;
+  resume?(sessionId: string, request: HarnessRequest): Promise<HarnessResult>;
+}
+
+export interface HarnessInspection {
+  adapter: HarnessAdapter;
+  availability: HarnessAvailability;
+  capabilities: HarnessCapabilities;
+}

package/src/output-mode.ts

@@ -0,0 +1,32 @@
+export type LisaOutputMode = "interactive" | "concise";
+
+type OutputModeOptions = {
+  env?: Record<string, string | undefined>;
+  isStdoutTTY?: boolean;
+};
+
+function resolveOverride(env: Record<string, string | undefined>): LisaOutputMode | undefined {
+  const override = env.LISA_OUTPUT_MODE?.trim().toLowerCase();
+  if (override === "interactive" || override === "concise") {
+    return override;
+  }
+
+  return undefined;
+}
+
+export function resolveOutputMode(
+  env: Record<string, string | undefined> = process.env,
+  stdout: { isTTY?: boolean } = process.stdout,
+): LisaOutputMode {
+  return resolveOverride(env) ?? (stdout.isTTY ? "interactive" : "concise");
+}
+
+export function getOutputMode(options: OutputModeOptions = {}): LisaOutputMode {
+  return resolveOutputMode(options.env ?? process.env, {
+    isTTY: options.isStdoutTTY ?? Boolean(process.stdout.isTTY),
+  });
+}
+
+export function isInteractiveOutput(options: OutputModeOptions = {}): boolean {
+  return getOutputMode(options) === "interactive";
+}

package/src/skill/artifacts.ts

@@ -0,0 +1,174 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
+
+import type { HarnessSkillInstallDefinition, HarnessSkillInstallResult } from "../harness/types";
+
+function resolveSkillsRoot(): string {
+  const candidates = [
+    join(import.meta.dir, "..", "..", "skills"),
+    join(import.meta.dir, "..", "skills"),
+  ];
+
+  return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
+}
+
+const SKILLS_ROOT = resolveSkillsRoot();
+
+export function resolveSkillArtifactPath(harnessId: string, fileName: string): string {
+  return join(SKILLS_ROOT, harnessId, fileName);
+}
+
+function resolveConfiguredAbsolutePath(envVarName: string, fallbackPath: () => string): string {
+  const configured = process.env[envVarName]?.trim();
+  if (!configured) {
+    return fallbackPath();
+  }
+
+  if (!isAbsolute(configured)) {
+    throw new Error(`${envVarName} must be an absolute path.`);
+  }
+
+  return configured;
+}
+
+export function resolveHomeDirectory(): string {
+  return resolveConfiguredAbsolutePath("HOME", () => homedir());
+}
+
+export function resolveXdgConfigHome(): string {
+  return resolveConfiguredAbsolutePath("XDG_CONFIG_HOME", () => join(resolveHomeDirectory(), ".config"));
+}
+
+export function resolveXdgDataHome(): string {
+  return resolveConfiguredAbsolutePath("XDG_DATA_HOME", () => join(resolveHomeDirectory(), ".local", "share"));
+}
+
+export function resolveXdgStateHome(): string {
+  return resolveConfiguredAbsolutePath("XDG_STATE_HOME", () => join(resolveHomeDirectory(), ".local", "state"));
+}
+
+export function resolveCodexHome(): string {
+  return resolveConfiguredAbsolutePath("CODEX_HOME", () => join(resolveHomeDirectory(), ".codex"));
+}
+
+export function resolveGeminiHome(): string {
+  return join(resolveHomeDirectory(), ".gemini");
+}
+
+export function resolveLocalSkillWorkspace(cwd = process.cwd()): string {
+  return resolve(cwd);
+}
+
+export function renderOpenCodeSkill(content: string): string {
+  const trimmed = content.trimEnd();
+  return `---\nname: lisa\ndescription: Follow Lisa's checked-in repository guidance.\nlicense: MIT\ncompatibility: opencode\n---\n\n${trimmed}\n`;
+}
+
+function isLisaManagedSkill(content: string): boolean {
+  const trimmed = content.trimStart();
+  return trimmed.startsWith("# Lisa for ") || /^---\r?\nname:\s*lisa(?:\r?\n|$)/.test(trimmed);
+}
+
+function isPathInsideRoot(rootPath: string, targetPath: string): boolean {
+  const relativePath = relative(rootPath, targetPath);
+  return relativePath !== ".."
+    && !relativePath.startsWith("../")
+    && !relativePath.startsWith("..\\")
+    && !/^[A-Za-z]:[\\/]/.test(relativePath)
+    && !relativePath.startsWith("\\\\");
+}
+
+function assertSafeInstallPath(rootPath: string, destinationPath: string, scope: "local" | "global"): void {
+  const rootBoundary = resolve(rootPath);
+  if (!isPathInsideRoot(rootBoundary, resolve(destinationPath))) {
+    throw new Error(`${scope === "local" ? "Local" : "Global"} skill installs must stay inside the configured ${scope} root.`);
+  }
+
+  let existingRootBoundary = rootBoundary;
+  while (!existsSync(existingRootBoundary)) {
+    const parentPath = dirname(existingRootBoundary);
+    if (parentPath === existingRootBoundary) {
+      break;
+    }
+
+    existingRootBoundary = parentPath;
+  }
+  const rootRealPath = existsSync(existingRootBoundary) ? realpathSync(existingRootBoundary) : undefined;
+
+  let existingPath = resolve(destinationPath);
+  while (!existsSync(existingPath)) {
+    const parentPath = dirname(existingPath);
+    if (parentPath === existingPath) {
+      throw new Error(`Could not resolve a safe parent directory for ${destinationPath}`);
+    }
+
+    existingPath = parentPath;
+  }
+
+  let cursor = existingPath;
+  while (true) {
+    if (lstatSync(cursor).isSymbolicLink()) {
+      throw new Error(`Refusing to install a ${scope} skill through a symlinked path: ${cursor}`);
+    }
+
+    if (cursor === existingRootBoundary) {
+      break;
+    }
+
+    const parentPath = dirname(cursor);
+    if (parentPath === cursor) {
+      break;
+    }
+
+    cursor = parentPath;
+  }
+
+  if (!rootRealPath) {
+    return;
+  }
+
+  const existingRealPath = realpathSync(existingPath);
+  if (!isPathInsideRoot(rootRealPath, existingRealPath)) {
+    throw new Error(`${scope === "local" ? "Local" : "Global"} skill installs must stay inside the configured ${scope} root.`);
+  }
+}
+
+export function installSkillArtifact(
+  definition: HarnessSkillInstallDefinition,
+  content?: string,
+  options: { rootPath?: string; scope: "local" | "global" } = { scope: "global" },
+): HarnessSkillInstallResult {
+  if (!existsSync(definition.sourcePath)) {
+    throw new Error(`Skill artifact not found: ${definition.sourcePath}`);
+  }
+
+  const nextContent = content ?? readFileSync(definition.sourcePath, "utf8");
+
+  if (options.rootPath) {
+    assertSafeInstallPath(options.rootPath, definition.destinationPath, options.scope);
+  }
+
+  const existed = existsSync(definition.destinationPath);
+  if (existed) {
+    const currentContent = readFileSync(definition.destinationPath, "utf8");
+    if (currentContent === nextContent) {
+      return {
+        ...definition,
+        status: "unchanged",
+      };
+    }
+
+    if (!isLisaManagedSkill(currentContent)) {
+      throw new Error(`Refusing to overwrite non-Lisa guidance at ${definition.destinationPath}`);
+    }
+  }
+
+  mkdirSync(dirname(definition.destinationPath), { recursive: true });
+  writeFileSync(definition.destinationPath, nextContent);
+
+  return {
+    ...definition,
+    status: existed ? "updated" : "created",
+  };
+}

package/src/skill/cli.ts

@@ -0,0 +1,29 @@
+import { runSkillInstallCommand } from "./install";
+
+function printSkillHelp(): void {
+  console.log(`Lisa skill commands
+
+Usage:
+  lisa skill install --local|--global
+
+Available today:
+  install         Install Lisa guidance for supported harnesses
+`);
+}
+
+export async function runSkillCli(args: string[], cwd = process.cwd()): Promise<number> {
+  const [command] = args;
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printSkillHelp();
+    return 0;
+  }
+
+  if (command === "install") {
+    return runSkillInstallCommand(args.slice(1), cwd);
+  }
+
+  console.error(`Unknown lisa skill command: ${command}`);
+  console.error("Run `lisa skill --help` for available commands.");
+  return 1;
+}