@wkronmiller/lisa 0.1.0

package/src/spec/workflows/init.ts

@@ -0,0 +1,548 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { dirname, join, relative, resolve } from "path";
+import { createInterface } from "readline/promises";
+import { stdin as input, stdout as output } from "process";
+
+import { inspectHarnesses } from "../../harness/registry";
+import type { HarnessInspection, Stage } from "../../harness/types";
+import { resolveOutputMode } from "../../output-mode";
+import { installLisaSkills, type SkillInstallResult } from "../../skill/install";
+import { initializeExternalWorkspace, resolveBootstrapWorkspaceRoot, resolveWorkspaceLayoutFromRoot } from "../workspace";
+
+interface InitCommandOptions {
+  force: boolean;
+  external: boolean;
+  globalPackRoots: string[];
+  help: boolean;
+}
+
+interface DefaultHarnessSelection {
+  generate: string;
+  implement: string;
+  check: string;
+  import: string;
+}
+
+interface InitWarnings {
+  noPortableHarnessDetected: boolean;
+}
+
+interface ScaffoldFile {
+  path: string;
+  content: string;
+}
+
+export interface InitCommandIO {
+  ask?(question: string): Promise<string>;
+  print(message: string): void;
+  error(message: string): void;
+  close?(): void;
+}
+
+export interface InitCommandDeps {
+  inspectHarnesses?: (cwd: string) => Promise<HarnessInspection[]>;
+  installLocalSkills?: (workspaceRoot: string) => Promise<SkillInstallResult[]>;
+}
+
+const PROFILE_NAMES: Record<Stage, string> = {
+  generate: "planner",
+  implement: "implementer",
+  check: "verifier",
+  import: "importer",
+};
+
+const PREFERRED_HARNESSES_BY_STAGE: Record<Stage, string[]> = {
+  generate: ["opencode", "claude-code", "codex", "gemini"],
+  implement: ["opencode", "codex", "claude-code", "gemini"],
+  check: ["claude-code", "codex", "gemini", "opencode"],
+  import: ["opencode", "claude-code", "codex", "gemini"],
+};
+
+const PROJECT_MD_TEMPLATE = `---
+# Project-level defaults for Lisa spec workflows.
+# Values here are included as harness context for all stages.
+# Individual spec frontmatter values take precedence over these defaults.
+---
+
+# Project
+
+- language: <!-- e.g. typescript, java, python -->
+- framework: <!-- e.g. express, spring-boot, django -->
+- default_code_paths: <!-- e.g. src/** -->
+- default_test_commands: <!-- e.g. bun test ./tests -->
+`;
+
+const STARTER_FILES = [
+  ["backend", ".gitkeep"],
+  ["frontend", ".gitkeep"],
+  ["environments", ".gitkeep"],
+] as const;
+
+const ALL_GUIDANCE_TARGETS = ["AGENTS.md", "CLAUDE.md", "GEMINI.md"] as const;
+
+function createConsoleIO(): InitCommandIO {
+  if (resolveOutputMode() !== "interactive" || !input.isTTY || !output.isTTY) {
+    return {
+      print(message: string): void {
+        console.log(message);
+      },
+      error(message: string): void {
+        console.error(message);
+      },
+    };
+  }
+
+  const rl = createInterface({ input, output });
+  return {
+    async ask(question: string): Promise<string> {
+      return rl.question(question);
+    },
+    print(message: string): void {
+      console.log(message);
+    },
+    error(message: string): void {
+      console.error(message);
+    },
+    close(): void {
+      rl.close();
+    },
+  };
+}
+
+function printInitHelp(io: InitCommandIO): void {
+  io.print(`Lisa spec init
+
+Usage:
+  lisa spec init [options]
+
+Options:
+  --external         Keep specs and runtime state outside the repository
+  --global-pack <path>
+                     Attach an explicit global pack root for external mode (repeatable)
+  --force            Overwrite the generated .specs/config.yaml scaffold
+  --help, -h         Show this help
+`);
+}
+
+function parseInitArgs(args: string[]): InitCommandOptions {
+  const options: InitCommandOptions = {
+    force: false,
+    external: false,
+    globalPackRoots: [],
+    help: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) {
+      continue;
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === "--force") {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === "--external") {
+      options.external = true;
+      continue;
+    }
+
+    if (arg === "--global-pack") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("--global-pack requires a value.");
+      }
+      options.globalPackRoots.push(resolve(value));
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown lisa spec init option: ${arg}`);
+  }
+
+  if (!options.external && options.globalPackRoots.length > 0) {
+    throw new Error("--global-pack can only be used with --external.");
+  }
+
+  return options;
+}
+
+function toPortablePath(path: string, workspacePath: string): string {
+  return relative(workspacePath, path).split("\\").join("/") || ".";
+}
+
+function normalizeBooleanAnswer(answer: string, fallback = false): boolean {
+  const normalized = answer.trim().toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+
+  if (["y", "yes"].includes(normalized)) {
+    return true;
+  }
+
+  if (["n", "no"].includes(normalized)) {
+    return false;
+  }
+
+  return fallback;
+}
+
+async function promptYesNo(io: InitCommandIO, question: string, fallback = false): Promise<boolean> {
+  if (!io.ask) {
+    return fallback;
+  }
+
+  const label = fallback ? "Y/n" : "y/N";
+  const answer = await io.ask(`${question} [${label}]: `);
+  return normalizeBooleanAnswer(answer, fallback);
+}
+
+function selectDefaultHarness(
+  inspections: HarnessInspection[],
+  stage: Stage,
+): string {
+  const availableHarnesses = new Set(
+    inspections
+      .filter((inspection) => (
+        inspection.availability.available
+        && inspection.adapter.supportedStages.includes(stage)
+      ))
+      .map((inspection) => inspection.adapter.id),
+  );
+
+  for (const harnessId of PREFERRED_HARNESSES_BY_STAGE[stage]) {
+    if (availableHarnesses.has(harnessId)) {
+      return harnessId;
+    }
+  }
+
+  return PREFERRED_HARNESSES_BY_STAGE[stage][0];
+}
+
+function selectDefaultHarnessesForWorkspace(
+  inspections: HarnessInspection[],
+): DefaultHarnessSelection {
+  return {
+    generate: selectDefaultHarness(inspections, "generate"),
+    implement: selectDefaultHarness(inspections, "implement"),
+    check: selectDefaultHarness(inspections, "check"),
+    import: selectDefaultHarness(inspections, "import"),
+  };
+}
+
+function collectInitWarnings(
+  inspections: HarnessInspection[],
+): InitWarnings {
+  const noPortableHarnessDetected = !inspections.some((inspection) => (
+    inspection.availability.available
+  ));
+
+  return {
+    noPortableHarnessDetected,
+  };
+}
+
+function renderHarnessConfig(): Record<string, { command: string; args: string[] }> {
+  return {
+    codex: {
+      command: "codex",
+      args: [],
+    },
+    opencode: {
+      command: "opencode",
+      args: [],
+    },
+    "claude-code": {
+      command: "claude",
+      args: [],
+    },
+    gemini: {
+      command: "gemini",
+      args: [],
+    },
+  };
+}
+
+function formatLocalSkillResult(result: SkillInstallResult, workspacePath: string): string {
+  const destination = toPortablePath(result.destinationPath, workspacePath);
+  if (result.state === "skipped" || result.state === "failed") {
+    return `- ${result.adapterId}: ${result.state} ${destination} (${result.reason ?? "unavailable"})`;
+  }
+
+  return `- ${result.adapterId}: ${result.state} ${destination}`;
+}
+
+function renderConfig(
+  selection: DefaultHarnessSelection,
+  enableAgentGuidance: boolean,
+  guidanceTargets: readonly string[] = ALL_GUIDANCE_TARGETS,
+): string {
+  return `${Bun.YAML.stringify({
+    default_stage_profiles: {
+      generate: PROFILE_NAMES.generate,
+      implement: PROFILE_NAMES.implement,
+      check: PROFILE_NAMES.check,
+      import: PROFILE_NAMES.import,
+    },
+    profiles: {
+      planner: {
+        harness: selection.generate,
+        allow_edits: false,
+      },
+      implementer: {
+        harness: selection.implement,
+        allow_edits: true,
+      },
+      verifier: {
+        harness: selection.check,
+        allow_edits: false,
+      },
+      importer: {
+        harness: selection.import,
+        allow_edits: false,
+      },
+    },
+    harnesses: renderHarnessConfig(),
+    agent_guidance: {
+      enabled: enableAgentGuidance,
+      targets: guidanceTargets,
+    },
+  }).trimEnd()}
+`;
+}
+
+function buildStarterFiles(specRoot: string): ScaffoldFile[] {
+  return [
+    ...STARTER_FILES.map(([directory, filename]) => ({
+      path: join(specRoot, directory, filename),
+      content: "",
+    })),
+    {
+      path: join(specRoot, "project.md"),
+      content: PROJECT_MD_TEMPLATE,
+    },
+  ];
+}
+
+function writeScaffoldFiles(files: ScaffoldFile[]): void {
+  for (const file of files) {
+    mkdirSync(dirname(file.path), { recursive: true });
+    writeFileSync(file.path, file.content);
+  }
+}
+
+function ensureGitignoreEntry(workspacePath: string, entry: string): boolean {
+  const gitignorePath = join(workspacePath, ".gitignore");
+  const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
+  const lines = existing.split("\n");
+
+  if (lines.some((line) => line.trim() === entry)) {
+    return false;
+  }
+
+  const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  writeFileSync(gitignorePath, `${existing}${separator}${entry}\n`);
+  return true;
+}
+
+function hasExistingRepoSpecWorkspace(workspacePath: string): boolean {
+  const specRoot = join(workspacePath, ".specs");
+  if (!existsSync(specRoot)) {
+    return false;
+  }
+
+  if (existsSync(join(specRoot, "config.yaml"))) {
+    return true;
+  }
+
+  for (const directory of ["backend", "frontend", "environments"]) {
+    const directoryPath = join(specRoot, directory);
+    if (!existsSync(directoryPath)) {
+      continue;
+    }
+
+    if (readdirSync(directoryPath).some((entry) => entry !== ".gitkeep")) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export async function runSpecInitCommand(
+  args: string[],
+  cwd = process.cwd(),
+  io: InitCommandIO = createConsoleIO(),
+  deps: InitCommandDeps = {},
+): Promise<number> {
+  try {
+    const options = parseInitArgs(args);
+    if (options.help) {
+      printInitHelp(io);
+      return 0;
+    }
+
+    const workspacePath = resolveBootstrapWorkspaceRoot(cwd);
+    if (options.external && hasExistingRepoSpecWorkspace(workspacePath)) {
+      io.error("`lisa spec init --external` refuses to hide an existing repo-local `.specs` workspace. Migrate or remove the repo-local Lisa workspace first.");
+      return 1;
+    }
+    const existingLayout = resolveWorkspaceLayoutFromRoot(workspacePath);
+    const globalPackRoots = options.globalPackRoots.length > 0
+      ? options.globalPackRoots
+      : existingLayout.storageMode === "external"
+        ? existingLayout.globalPackRoots
+        : [];
+    const layout = options.external
+      ? initializeExternalWorkspace(workspacePath, globalPackRoots)
+      : existingLayout;
+    const configPath = layout.configPath;
+    const specRoot = dirname(configPath);
+    const shouldWriteConfig = options.force || !existsSync(configPath);
+
+    mkdirSync(join(specRoot, "backend"), { recursive: true });
+    mkdirSync(join(specRoot, "frontend"), { recursive: true });
+    mkdirSync(join(specRoot, "environments"), { recursive: true });
+    if (layout.worktreeSpecRoot) {
+      mkdirSync(layout.worktreeSpecRoot, { recursive: true });
+    }
+    mkdirSync(layout.runtimeRoot, { recursive: true });
+    mkdirSync(layout.snapshotRoot, { recursive: true });
+
+    const scaffoldFiles = buildStarterFiles(specRoot).filter((file) => !existsSync(file.path));
+    let defaultHarnesses: DefaultHarnessSelection | undefined;
+    let warnings: InitWarnings | undefined;
+    let ranLocalSetup = false;
+    const filesToWrite: ScaffoldFile[] = [...scaffoldFiles];
+
+    if (shouldWriteConfig) {
+      const inspect = deps.inspectHarnesses ?? inspectHarnesses;
+      const inspections = await inspect(workspacePath);
+      defaultHarnesses = selectDefaultHarnessesForWorkspace(
+        inspections,
+      );
+      warnings = collectInitWarnings(inspections);
+    }
+
+    io.print("Lisa spec init");
+    io.print("");
+    io.print(`Workspace: ${workspacePath}`);
+    io.print(`Storage: ${layout.storageMode}`);
+    io.print(`Spec root: ${specRoot}`);
+    if (layout.worktreeSpecRoot) {
+      io.print(`Worktree spec root: ${layout.worktreeSpecRoot}`);
+    }
+    if (layout.globalPackRoots.length > 0) {
+      io.print(`Global pack roots: ${layout.globalPackRoots.join(", ")}`);
+    }
+    io.print(`Runtime root: ${layout.runtimeRoot}`);
+    io.print(`Snapshot root: ${layout.snapshotRoot}`);
+
+    if (shouldWriteConfig && io.ask && layout.storageMode !== "external") {
+      ranLocalSetup = await promptYesNo(
+        io,
+        "Install local Lisa skills now?",
+        false,
+      );
+    }
+
+    if (shouldWriteConfig && defaultHarnesses) {
+      filesToWrite.unshift({
+        path: configPath,
+        content: renderConfig(defaultHarnesses, false, []),
+      });
+    }
+
+    if (filesToWrite.length === 0) {
+      io.print("Status: already initialized");
+      io.print(`Config: present (${toPortablePath(configPath, workspacePath)})`);
+      io.print("");
+      io.print("Nothing to write. Re-run with `lisa spec init --force` to replace the scaffolded config.");
+      return 0;
+    }
+
+    writeScaffoldFiles(filesToWrite);
+    const addedGitignore = layout.storageMode === "external" ? false : ensureGitignoreEntry(workspacePath, ".specs/config.local.yaml");
+
+    let localSkillResults: SkillInstallResult[] = [];
+    if (ranLocalSetup) {
+      const installLocalSkills = deps.installLocalSkills ?? ((root: string) => installLisaSkills("local", root));
+
+      localSkillResults = await installLocalSkills(workspacePath);
+    }
+
+    io.print(`Status: ${shouldWriteConfig ? (options.force ? "refreshed" : "initialized") : "updated"}`);
+    io.print("");
+    io.print("Wrote files:");
+    for (const file of filesToWrite) {
+      io.print(`- ${toPortablePath(file.path, workspacePath)}`);
+    }
+
+    if (addedGitignore) {
+      io.print(`- .gitignore (added .specs/config.local.yaml)`);
+    }
+
+    if (localSkillResults.length > 0) {
+      io.print("");
+      io.print("Local Lisa skill install:");
+      for (const result of localSkillResults) {
+        io.print(formatLocalSkillResult(result, workspacePath));
+      }
+    }
+
+    const localSkillInstallFailed = localSkillResults.some((result) => result.state === "failed");
+
+    if (!shouldWriteConfig) {
+      io.print("");
+      io.print(`Preserved existing config at ${toPortablePath(configPath, workspacePath)}.`);
+    }
+
+    if (defaultHarnesses) {
+      io.print("");
+      io.print("Default stage profiles:");
+      io.print(`- generate -> ${PROFILE_NAMES.generate} (${defaultHarnesses.generate})`);
+      io.print(`- implement -> ${PROFILE_NAMES.implement} (${defaultHarnesses.implement})`);
+      io.print(`- check -> ${PROFILE_NAMES.check} (${defaultHarnesses.check})`);
+      io.print(`- import -> ${PROFILE_NAMES.import} (${defaultHarnesses.import})`);
+
+      if (warnings?.noPortableHarnessDetected) {
+        io.print("");
+        io.print("Warning: No portable harness CLI was detected for this repo.");
+        io.print("The scaffold uses standard command names, so install or reconfigure a harness before running spec stages.");
+      }
+    }
+
+    io.print("");
+    io.print("Next steps:");
+    io.print("- Run `lisa spec status` to confirm harness availability.");
+    if (layout.storageMode === "external") {
+      io.print("- Run `lisa spec guide backend <name>`, `lisa spec generate`, or `lisa spec import` to author specs in Lisa's external storage roots.");
+      io.print("- Run `lisa skill install --local` later only if you explicitly want repo-local harness guidance files.");
+    } else if (shouldWriteConfig && !ranLocalSetup) {
+      io.print("- Run `lisa skill install --local` later if you want Lisa to install repo-local harness guidance files.");
+      io.print("- If you want managed Lisa guidance updates later, point `agent_guidance.targets` at a non-root repo file instead of AGENTS.md/CLAUDE.md/GEMINI.md.");
+      io.print("- Run `lisa spec generate backend <name>` or `lisa spec import <path...>` to create your first specs.");
+    } else {
+      io.print("- Run `lisa spec generate backend <name>` or `lisa spec import <path...>` to create your first specs.");
+    }
+
+    if (localSkillInstallFailed) {
+      io.error("Local Lisa skill install did not complete for every detected harness.");
+      return 1;
+    }
+
+    return 0;
+  } catch (error) {
+    io.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  } finally {
+    io.close?.();
+  }
+}

package/src/spec/workflows/status.ts

@@ -0,0 +1,22 @@
+import { inspectHarnesses } from "../../harness/registry";
+import type { HarnessInspection } from "../../harness/types";
+import type { SpecWorkspaceSnapshot } from "../types";
+import { inspectSpecWorkspace } from "../workspace";
+
+export interface SpecStatusReport {
+  workspace: SpecWorkspaceSnapshot;
+  harnesses: HarnessInspection[];
+  availableHarnesses: HarnessInspection[];
+}
+
+export async function runSpecStatusWorkflow(cwd = process.cwd()): Promise<SpecStatusReport> {
+  const workspace = inspectSpecWorkspace(cwd);
+  const harnesses = await inspectHarnesses(workspace.workspacePath);
+  const availableHarnesses = harnesses.filter((inspection) => inspection.availability.available);
+
+  return {
+    workspace,
+    harnesses,
+    availableHarnesses,
+  };
+}