@wkronmiller/lisa 0.1.0

package/src/skill/install.ts

@@ -0,0 +1,317 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from "fs";
+import { basename, dirname, join, relative, resolve } from "path";
+
+import { getHarnessAdapters } from "../harness/registry";
+import type { HarnessAdapter, HarnessSkillInstallDefinition, SkillInstallScope } from "../harness/types";
+import { resolveBootstrapWorkspaceRoot, resolveWorkspaceRoot } from "../spec/workspace";
+
+export type SkillInstallState = "created" | "updated" | "unchanged" | "skipped" | "failed";
+
+export interface SkillInstallResult {
+  adapterId: string;
+  scope: SkillInstallScope;
+  sourcePath: string;
+  destinationPath: string;
+  state: SkillInstallState;
+  reason?: string;
+}
+
+interface InstallCommandOptions {
+  help: boolean;
+  scope?: SkillInstallScope;
+}
+
+function isRepoInstructionFile(path: string): boolean {
+  return ["AGENTS.md", "CLAUDE.md", "GEMINI.md"].includes(basename(path));
+}
+
+function containsLisaSubstring(content: string): boolean {
+  return content.toLowerCase().includes("lisa");
+}
+
+function hasManagedGuidanceBlock(content: string): boolean {
+  return content.includes("<!-- LISA_AGENT_GUIDANCE_START -->")
+    && content.includes("<!-- LISA_AGENT_GUIDANCE_END -->");
+}
+
+function isRepositoryWorkspace(path: string): boolean {
+  let current = resolve(path);
+
+  while (true) {
+    if (existsSync(join(current, ".git")) || existsSync(join(current, ".specs")) || existsSync(join(current, ".lisa"))) {
+      return true;
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      return false;
+    }
+
+    current = parent;
+  }
+}
+
+function printInstallHelp(): void {
+  console.log(`Lisa skill install
+
+Usage:
+  lisa skill install --local
+  lisa skill install --global
+
+Options:
+  --local            Install Lisa guidance into the current repository
+  --global           Install Lisa guidance into global harness config roots
+  --help, -h         Show this help
+`);
+}
+
+function parseInstallArgs(args: string[]): InstallCommandOptions {
+  const options: InstallCommandOptions = { help: false };
+
+  for (const arg of args) {
+    if (!arg) {
+      continue;
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === "--local" || arg === "--global") {
+      if (options.scope && options.scope !== arg.slice(2)) {
+        throw new Error("Choose exactly one install scope: `--local` or `--global`.");
+      }
+
+      options.scope = arg.slice(2) as SkillInstallScope;
+      continue;
+    }
+
+    throw new Error(`Unknown lisa skill install option: ${arg}`);
+  }
+
+  return options;
+}
+
+function normalizePortablePath(path: string, basePath: string): string {
+  return relative(basePath, path).split("\\").join("/") || ".";
+}
+
+function resolveExistingPath(path: string): string {
+  let current = resolve(path);
+
+  while (!existsSync(current)) {
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+
+    current = parent;
+  }
+
+  return current;
+}
+
+function isPathInsideWorkspace(rootPath: string, targetPath: string): boolean {
+  const workspaceRealPath = realpathSync(rootPath);
+  const targetRealPath = realpathSync(resolveExistingPath(targetPath));
+  return targetRealPath === workspaceRealPath || targetRealPath.startsWith(`${workspaceRealPath}/`);
+}
+
+function resolveDefinition(adapter: HarnessAdapter, scope: SkillInstallScope): Promise<HarnessSkillInstallDefinition> {
+  if (!adapter.getSkillInstallDefinition) {
+    throw new Error(`Harness \`${adapter.id}\` does not expose Lisa skill install metadata.`);
+  }
+
+  return adapter.getSkillInstallDefinition(scope);
+}
+
+function readCanonicalContent(definition: HarnessSkillInstallDefinition): string {
+  return readFileSync(definition.sourcePath, "utf8");
+}
+
+function resolveLocalRootInstructionAction(definition: HarnessSkillInstallDefinition): { skip: true; reason: string } | { skip: false } {
+  if (!isRepoInstructionFile(definition.destinationPath) || !existsSync(definition.destinationPath)) {
+    return { skip: false };
+  }
+
+  if (lstatSync(definition.destinationPath).isSymbolicLink()) {
+    return { skip: false };
+  }
+
+  const existingContent = readFileSync(definition.destinationPath, "utf8");
+  if (hasManagedGuidanceBlock(existingContent)) {
+    return { skip: true, reason: "existing file preserved" };
+  }
+
+  if (existingContent === readCanonicalContent(definition)) {
+    return { skip: false };
+  }
+
+  if (containsLisaSubstring(existingContent)) {
+    return { skip: true, reason: "existing file already contains lisa" };
+  }
+
+  return { skip: true, reason: "existing file preserved" };
+}
+
+function unresolvedResult(adapterId: string, scope: SkillInstallScope, reason: string, state: SkillInstallState): SkillInstallResult {
+  return {
+    adapterId,
+    scope,
+    sourcePath: "(unresolved)",
+    destinationPath: "(unresolved)",
+    state,
+    reason,
+  };
+}
+
+function formatInstallResult(result: SkillInstallResult, workspaceRoot: string): string {
+  const destination = result.scope === "local" && result.destinationPath !== "(unresolved)"
+    ? normalizePortablePath(result.destinationPath, workspaceRoot)
+    : result.destinationPath;
+  const source = result.sourcePath === "(unresolved)"
+    ? result.sourcePath
+    : normalizePortablePath(resolve(result.sourcePath), workspaceRoot);
+
+  if (result.state === "skipped" || result.state === "failed") {
+    return `- ${result.adapterId}: ${result.state} ${destination} (${result.reason ?? "unavailable"}; source ${source})`;
+  }
+
+  return `- ${result.adapterId}: ${result.state} ${destination} (source ${source})`;
+}
+
+export async function installLisaSkills(
+  scope: SkillInstallScope,
+  workspaceRoot: string,
+  adapters = getHarnessAdapters(workspaceRoot),
+): Promise<SkillInstallResult[]> {
+  const results: SkillInstallResult[] = [];
+
+  for (const adapter of adapters) {
+    let definition: HarnessSkillInstallDefinition | undefined;
+
+    try {
+      definition = await resolveDefinition(adapter, scope);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const availability = await adapter.detect();
+      results.push(unresolvedResult(adapter.id, scope, availability.available ? message : availability.reason, availability.available ? "failed" : "skipped"));
+      continue;
+    }
+
+    const availability = await adapter.detect();
+    if (!availability.available) {
+      results.push({
+        adapterId: adapter.id,
+        scope,
+        sourcePath: definition.sourcePath,
+        destinationPath: definition.destinationPath,
+        state: "skipped",
+        reason: availability.reason,
+      });
+      continue;
+    }
+
+    if (scope === "global" && isPathInsideWorkspace(workspaceRoot, definition.destinationPath)) {
+      results.push({
+        adapterId: adapter.id,
+        scope,
+        sourcePath: definition.sourcePath,
+        destinationPath: definition.destinationPath,
+        state: "failed",
+        reason: `Global install target must stay outside the repository: ${definition.destinationPath}`,
+      });
+      continue;
+    }
+
+    const localRootAction = scope === "local" ? resolveLocalRootInstructionAction(definition) : { skip: false as const };
+    if (localRootAction.skip) {
+      results.push({
+        adapterId: adapter.id,
+        scope,
+        sourcePath: definition.sourcePath,
+        destinationPath: definition.destinationPath,
+        state: "skipped",
+        reason: localRootAction.reason,
+      });
+      continue;
+    }
+
+    if (!adapter.installSkill) {
+      results.push(unresolvedResult(adapter.id, scope, `Harness \`${adapter.id}\` cannot install Lisa guidance.`, "failed"));
+      continue;
+    }
+
+    try {
+      const installed = await adapter.installSkill(scope);
+      results.push({
+        adapterId: adapter.id,
+        scope,
+        sourcePath: installed.sourcePath,
+        destinationPath: installed.destinationPath,
+        state: installed.status,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      results.push({
+        adapterId: adapter.id,
+        scope,
+        sourcePath: definition.sourcePath,
+        destinationPath: definition.destinationPath,
+        state: "failed",
+        reason: message,
+      });
+    }
+  }
+
+  return results;
+}
+
+export async function runSkillInstallCommand(args: string[], cwd = process.cwd()): Promise<number> {
+  try {
+    const options = parseInstallArgs(args);
+    if (options.help) {
+      printInstallHelp();
+      return 0;
+    }
+
+    if (!options.scope) {
+      throw new Error("Install scope required. Use `--local` or `--global`.");
+    }
+
+    const workspaceRoot = options.scope === "local"
+      ? resolveBootstrapWorkspaceRoot(cwd)
+      : resolveWorkspaceRoot(cwd);
+
+    if (options.scope === "local" && !isRepositoryWorkspace(workspaceRoot)) {
+      throw new Error("`lisa skill install --local` must be run from inside a repository or Lisa workspace.");
+    }
+
+    const results = await installLisaSkills(options.scope, workspaceRoot);
+    const installedCount = results.filter((result) => ["created", "updated", "unchanged"].includes(result.state)).length;
+    const skippedCount = results.filter((result) => result.state === "skipped").length;
+    const failedCount = results.filter((result) => result.state === "failed").length;
+
+    console.log("Lisa skill install");
+    console.log("");
+    console.log(`Scope: ${options.scope}`);
+    console.log(`Workspace: ${workspaceRoot}`);
+    console.log("");
+    console.log(`Installed: ${installedCount}`);
+    console.log(`Skipped: ${skippedCount}`);
+    if (failedCount > 0) {
+      console.log(`Failed: ${failedCount}`);
+    }
+
+    console.log("");
+    for (const result of results) {
+      console.log(formatInstallResult(result, workspaceRoot));
+    }
+
+    return failedCount > 0 ? 1 : 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}