@wkronmiller/lisa 0.1.0

package/src/spec/workflows/guide.ts

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+
+import { getHarnessAdapterById } from "../../harness/registry";
+import { assertSafeRepoWritePath, ensureGuidanceSkillArtifact, renderSeedSpec, resolveGuidanceHarnessId } from "../agent-guidance";
+import { loadSpecWorkspace } from "../loader";
+import type { SpecArea } from "../types";
+import { SPEC_AREAS } from "../types";
+import { assertSafeLisaStorageWritePath, resolveSpecWriteRoot, resolveWorkspaceLayout, toLogicalPath, type SpecWriteScope } from "../workspace";
+
+interface GuideCommandOptions {
+  area?: SpecArea;
+  name?: string;
+  harness?: string;
+  scope?: SpecWriteScope;
+  help: boolean;
+}
+
+export interface GuideCommandIO {
+  print(message: string): void;
+  error(message: string): void;
+}
+
+function createConsoleIO(): GuideCommandIO {
+  return {
+    print(message: string): void {
+      console.log(message);
+    },
+    error(message: string): void {
+      console.error(message);
+    },
+  };
+}
+
+function printGuideHelp(io: GuideCommandIO): void {
+  io.print(`Lisa spec guide
+
+Usage:
+  lisa spec guide [backend|frontend] [name] [options]
+
+Options:
+  --harness <id>     Select the coding harness whose Lisa skill you want to use
+  --scope <name>     Write to the shared repo layer or worktree override layer
+  --help, -h         Show this help
+`);
+}
+
+function normalizeSpecName(inputName: string): string {
+  return inputName
+    .trim()
+    .replace(/\.md$/i, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function parseGuideArgs(args: string[]): GuideCommandOptions {
+  const positionals: string[] = [];
+  const options: GuideCommandOptions = { 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 === "--harness") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("--harness requires a value.");
+      }
+      options.harness = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--scope") {
+      const value = args[index + 1];
+      if (value !== "repo" && value !== "worktree") {
+        throw new Error("--scope requires `repo` or `worktree`.");
+      }
+      options.scope = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown lisa spec guide option: ${arg}`);
+    }
+
+    positionals.push(arg);
+  }
+
+  if (positionals[0] && SPEC_AREAS.includes(positionals[0] as SpecArea)) {
+    options.area = positionals[0] as SpecArea;
+  } else if (positionals[0]) {
+    throw new Error(`Expected first positional argument to be one of: ${SPEC_AREAS.join(", ")}.`);
+  }
+
+  if (positionals[1]) {
+    options.name = positionals[1];
+  }
+
+  if (!options.help && (!options.area || !options.name)) {
+    throw new Error("lisa spec guide requires [backend|frontend] and [name].");
+  }
+
+  if (positionals.length > 2) {
+    throw new Error("lisa spec guide accepts at most two positional arguments: [backend|frontend] [name].");
+  }
+
+  return options;
+}
+
+export async function runSpecGuideCommand(
+  args: string[],
+  cwd = process.cwd(),
+  io: GuideCommandIO = createConsoleIO(),
+): Promise<number> {
+  try {
+    const options = parseGuideArgs(args);
+    if (options.help) {
+      printGuideHelp(io);
+      return 0;
+    }
+
+    const layout = resolveWorkspaceLayout(cwd);
+    const workspaceRoot = layout.workspacePath;
+    const workspace = loadSpecWorkspace(workspaceRoot);
+    const area = options.area as SpecArea;
+    const name = normalizeSpecName(options.name as string);
+    if (!name) {
+      throw new Error("Spec name must contain at least one alphanumeric character.");
+    }
+
+    const harnessId = resolveGuidanceHarnessId(workspace.config, options.harness);
+    const harness = getHarnessAdapterById(harnessId, workspaceRoot);
+    if (!harness) {
+      throw new Error(`No harness adapter is registered for \`${harnessId}\`.`);
+    }
+
+    const skillArtifact = ensureGuidanceSkillArtifact(workspaceRoot, harnessId);
+
+    const targetPath = join(resolveSpecWriteRoot(workspaceRoot, options.scope ?? "repo"), area, `${name}.md`);
+    const relativeTargetPath = toLogicalPath(layout, targetPath);
+    const existingDocument = workspace.documents.find((document) => toLogicalPath(layout, document.path) === relativeTargetPath);
+    const existed = existsSync(targetPath);
+    let status = existed ? "reused existing spec" : "created draft seed spec";
+    if (!existed) {
+      if (layout.storageMode === "repo") {
+        assertSafeRepoWritePath(workspaceRoot, targetPath);
+      } else {
+        assertSafeLisaStorageWritePath(resolveSpecWriteRoot(workspaceRoot, options.scope ?? "repo"), targetPath, "Lisa spec guide");
+      }
+      mkdirSync(dirname(targetPath), { recursive: true });
+      if (layout.storageMode === "external" && options.scope === "worktree" && existingDocument) {
+        writeFileSync(targetPath, readFileSync(existingDocument.path, "utf8"));
+        status = "created worktree override from existing spec";
+      } else {
+        writeFileSync(targetPath, renderSeedSpec(area, name));
+      }
+    }
+
+    io.print("Lisa spec guide");
+    io.print("");
+    io.print(`Target spec: ${relativeTargetPath}`);
+    io.print(`Status: ${status}`);
+    io.print(`Harness skill: ${skillArtifact}`);
+    if (layout.storageMode === "external") {
+      io.print(`Storage layer: ${options.scope === "worktree" ? "worktree" : "repo"}`);
+    }
+    io.print("");
+    io.print("Next steps");
+    io.print(`- Open ${relativeTargetPath} in your ${harness.displayName} session with the guidance from ${skillArtifact}.`);
+    io.print("- Replace the placeholder code_paths, test_paths or test_commands, Summary, Use Cases, Invariants, Failure Modes, Acceptance Criteria, and Out of Scope content before implementation.");
+    if (!workspace.config) {
+      io.print("- Run `lisa spec init` before diff, implement, or check so the repository has a `.specs/config.yaml` stage profile setup.");
+    }
+    io.print("- When the spec is ready, run `lisa spec diff`, `lisa spec implement`, and `lisa spec check --changed` from this repository.");
+    return 0;
+  } catch (error) {
+    io.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}