@wkronmiller/lisa 0.1.0

package/src/spec/agent-guidance.ts

@@ -0,0 +1,466 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { basename, dirname, join, relative, resolve } from "path";
+import { fileURLToPath } from "url";
+
+import { getHarnessAdapters } from "../harness/registry";
+import { renderOpenCodeSkill } from "../skill/artifacts";
+import { normalizeRelativePath } from "./path-utils";
+import { resolveConfiguredHarnessId } from "./config";
+import { loadSpecWorkspace } from "./loader";
+import { LISA_ROOT_GUIDANCE } from "./skill-content";
+import type { LoadedSpecWorkspace, ParsedSpecConfig, SpecArea } from "./types";
+import { assertSafeLisaStorageWritePath, resolveWorkspaceLayout, toLogicalPath } from "./workspace";
+
+const MANAGED_GUIDANCE_START = "<!-- LISA_AGENT_GUIDANCE_START -->";
+const MANAGED_GUIDANCE_END = "<!-- LISA_AGENT_GUIDANCE_END -->";
+
+const WORKSPACE_SKILL_ARTIFACT_PATHS: Record<string, string> = {
+  codex: "skills/codex/AGENTS.md",
+  opencode: ".opencode/skills/lisa/SKILL.md",
+  "claude-code": "skills/claude-code/CLAUDE.md",
+  gemini: "skills/gemini/GEMINI.md",
+};
+
+const BUNDLED_SKILL_ARTIFACT_PATHS: Record<string, string> = {
+  codex: "skills/codex/AGENTS.md",
+  opencode: "skills/opencode/AGENTS.md",
+  "claude-code": "skills/claude-code/CLAUDE.md",
+  gemini: "skills/gemini/GEMINI.md",
+};
+
+function isRootGuidanceTarget(target: string): boolean {
+  return ["AGENTS.md", "CLAUDE.md", "GEMINI.md"].includes(target);
+}
+
+function containsLisaSubstring(content: string): boolean {
+  return content.toLowerCase().includes("lisa");
+}
+
+function resolveRootGuidanceHarnessId(target: string): string | undefined {
+  return target === "AGENTS.md"
+    ? "codex"
+    : target === "CLAUDE.md"
+      ? "claude-code"
+      : target === "GEMINI.md"
+        ? "gemini"
+        : undefined;
+}
+
+function matchesBundledRootGuidance(target: string, content: string): boolean {
+  const harnessId = resolveRootGuidanceHarnessId(target);
+  const bundledPath = harnessId ? getBundledSkillArtifactPathForHarness(harnessId) : undefined;
+  return Boolean(bundledPath && readFileSync(bundledPath, "utf8") === content);
+}
+
+function isSafeRepoRelativePath(path: string): boolean {
+  const raw = path.replace(/\\/g, "/").trim();
+  if (!raw || raw.startsWith("/") || /^[A-Za-z]:\//.test(raw)) {
+    return false;
+  }
+
+  const normalized = normalizeRelativePath(raw).trim();
+
+  return !normalized.split("/").some((segment) => segment.length === 0 || segment === "..");
+}
+
+function isReservedLisaPath(path: string): boolean {
+  const normalized = normalizeRelativePath(path).trim();
+  return normalized === ".specs"
+    || normalized.startsWith(".specs/")
+    || normalized === ".lisa"
+    || normalized.startsWith(".lisa/");
+}
+
+function getWorkspaceSkillArtifactPathForHarness(harnessId: string): string | undefined {
+  return WORKSPACE_SKILL_ARTIFACT_PATHS[harnessId];
+}
+
+function getBundledSkillArtifactPathForHarness(harnessId: string): string | undefined {
+  const bundledRelativePath = BUNDLED_SKILL_ARTIFACT_PATHS[harnessId] ?? getWorkspaceSkillArtifactPathForHarness(harnessId);
+  if (!bundledRelativePath) {
+    return undefined;
+  }
+
+  const candidates = [
+    fileURLToPath(new URL(`../../${bundledRelativePath}`, import.meta.url)),
+    fileURLToPath(new URL(`../${bundledRelativePath}`, import.meta.url)),
+  ];
+
+  return candidates.find((candidatePath) => existsSync(candidatePath));
+}
+
+function resolveMaterializedSkillArtifactPath(layout: ReturnType<typeof resolveWorkspaceLayout>, harnessId: string): string | undefined {
+  const fileName = harnessId === "opencode"
+    ? "SKILL.md"
+    : basename(getWorkspaceSkillArtifactPathForHarness(harnessId) ?? "");
+  if (!fileName) {
+    return undefined;
+  }
+
+  return join(layout.runtimeRoot, "skills", harnessId, fileName);
+}
+
+function formatSkillArtifactPath(layout: ReturnType<typeof resolveWorkspaceLayout>, artifactPath: string): string {
+  return toLogicalPath(layout, artifactPath);
+}
+
+export function ensureGuidanceSkillArtifact(workspaceRoot: string, harnessId: string): string {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  const workspaceRelativePath = getWorkspaceSkillArtifactPathForHarness(harnessId);
+  if (workspaceRelativePath && existsSync(join(workspaceRoot, workspaceRelativePath))) {
+    return workspaceRelativePath;
+  }
+
+  const bundledPath = getBundledSkillArtifactPathForHarness(harnessId);
+  const materializedPath = resolveMaterializedSkillArtifactPath(layout, harnessId);
+  if (!bundledPath || !materializedPath || !existsSync(bundledPath)) {
+    throw new Error(`No Lisa skill artifact is available for harness \`${harnessId}\`.`);
+  }
+
+  if (layout.storageMode === "repo") {
+    assertSafeRepoWritePath(workspaceRoot, materializedPath);
+  } else {
+    assertSafeLisaStorageWritePath(layout.runtimeRoot, materializedPath, "Lisa guidance skill artifact");
+  }
+  mkdirSync(dirname(materializedPath), { recursive: true });
+  const bundledContent = readFileSync(bundledPath, "utf8");
+  writeFileSync(materializedPath, harnessId === "opencode" ? renderOpenCodeSkill(bundledContent) : bundledContent);
+  if (layout.storageMode === "external") {
+    return materializedPath;
+  }
+
+  return formatSkillArtifactPath(layout, materializedPath);
+}
+
+export function resolveGuidanceHarnessId(config: ParsedSpecConfig | undefined, override?: string): string {
+  if (override) {
+    return config ? resolveConfiguredHarnessId(config, override) : override;
+  }
+
+  const profileName = config?.defaultStageProfiles.generate;
+  const harnessId = profileName ? config?.profiles[profileName]?.harness : undefined;
+  return config && harnessId ? resolveConfiguredHarnessId(config, harnessId) : harnessId ?? "opencode";
+}
+
+export function renderSeedSpec(area: SpecArea, name: string): string {
+  return `---
+id: ${area}.${name}
+status: draft
+code_paths:
+  - "TODO: replace with repo-relative code paths"
+test_paths:
+  - "TODO: replace with mapped test paths or remove this key if you only use test_commands"
+test_commands:
+  - "TODO: replace with deterministic test commands"
+---
+
+# Summary
+TODO: Replace this seed summary with the intended behavior.
+
+## Use Cases
+- TODO: Describe the primary user or system flow.
+
+## Invariants
+- TODO: Capture the behavior that must always remain true.
+
+## Failure Modes
+- TODO: Record important edge cases, failure handling, or safety constraints.
+
+## Acceptance Criteria
+- TODO: Add specific observable outcomes that prove the behavior works.
+
+## Out of Scope
+- TODO: List behavior this spec does not intend to cover.
+`;
+}
+
+function normalizeFrontmatterStringList(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+function resolveAdvertisedSkillArtifactPath(workspaceRoot: string, harnessId: string): string | undefined {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  const localInstallPath = harnessId === "codex"
+    ? "AGENTS.md"
+    : harnessId === "claude-code"
+      ? "CLAUDE.md"
+      : harnessId === "gemini"
+        ? "GEMINI.md"
+        : harnessId === "opencode"
+          ? ".opencode/skills/lisa/SKILL.md"
+          : undefined;
+  if (
+    localInstallPath
+    && existsSync(join(workspaceRoot, localInstallPath))
+    && (
+      !isRootGuidanceTarget(localInstallPath)
+      || (() => {
+        const content = readFileSync(join(workspaceRoot, localInstallPath), "utf8");
+        return content.includes(MANAGED_GUIDANCE_START) || matchesBundledRootGuidance(localInstallPath, content);
+      })()
+    )
+  ) {
+    return localInstallPath;
+  }
+
+  const resolvedMaterializedPath = resolveMaterializedSkillArtifactPath(layout, harnessId);
+  if (resolvedMaterializedPath && existsSync(resolvedMaterializedPath)) {
+    return formatSkillArtifactPath(layout, resolvedMaterializedPath);
+  }
+
+  const workspacePath = getWorkspaceSkillArtifactPathForHarness(harnessId);
+  if (workspacePath && existsSync(join(workspaceRoot, workspacePath))) {
+    return workspacePath;
+  }
+
+  const bundledPath = getBundledSkillArtifactPathForHarness(harnessId);
+  if (bundledPath) {
+    const relativeBundledPath = normalizeRelativePath(relative(workspaceRoot, bundledPath));
+    if (relativeBundledPath && relativeBundledPath !== ".." && !relativeBundledPath.startsWith("../")) {
+      return relativeBundledPath;
+    }
+  }
+
+  if (resolvedMaterializedPath) {
+    return formatSkillArtifactPath(layout, resolvedMaterializedPath);
+  }
+
+  return undefined;
+}
+
+function renderManagedGuidanceContent(workspace: LoadedSpecWorkspace): string {
+  const commandLines = [
+    "- `lisa skill install --global|--local`",
+    "- `lisa spec init`",
+    "- `lisa spec config [options]`",
+    "- `lisa spec status`",
+    "- `lisa spec harness list`",
+    "- `lisa spec guide [backend|frontend] [name] [options]`",
+    "- `lisa spec generate [backend|frontend] [name] [options]`",
+    "- `lisa spec diff [options]`",
+    "- `lisa spec implement [options]`",
+    "- `lisa spec check --changed|--all [options]`",
+    "- `lisa spec import <path...> [options]`",
+  ];
+  const harnessLines = getHarnessAdapters(workspace.workspacePath)
+    .map((adapter) => {
+      const artifactPath = resolveAdvertisedSkillArtifactPath(workspace.workspacePath, adapter.id);
+      return artifactPath ? `- \`${adapter.id}\` -> \`${artifactPath}\`` : `- \`${adapter.id}\``;
+    });
+  const activeSpecLines = workspace.documents
+    .filter((document) => document.kind === "base" && document.status === "active" && document.id)
+    .map((document) => {
+      const codePaths = normalizeFrontmatterStringList(document.frontmatter.code_paths);
+      const testPaths = normalizeFrontmatterStringList(document.frontmatter.test_paths);
+      const testCommands = normalizeFrontmatterStringList(document.frontmatter.test_commands);
+      const codePointer = codePaths.length > 0 ? codePaths.join(", ") : "none declared";
+      const testPointerParts = [
+        testPaths.length > 0 ? testPaths.join(", ") : "",
+        testCommands.length > 0 ? testCommands.join(", ") : "",
+      ].filter((entry) => entry.length > 0);
+      const testPointer = testPointerParts.length > 0 ? testPointerParts.join("; ") : "none declared";
+      return `- \`${document.id}\`: code ${codePointer}; tests ${testPointer}`;
+    });
+
+  const lines = [
+    MANAGED_GUIDANCE_START,
+    "## Lisa",
+    "",
+    "This block is managed by Lisa. Edit outside these markers.",
+    "",
+    LISA_ROOT_GUIDANCE,
+    "",
+    "### Current CLI surface",
+    ...commandLines,
+    "",
+    "### Harness skill artifacts",
+    ...harnessLines,
+    "",
+    "### Active spec pointers",
+    ...(activeSpecLines.length > 0 ? activeSpecLines : ["- No active base specs yet."]),
+    MANAGED_GUIDANCE_END,
+  ];
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function upsertManagedGuidance(existingContent: string, blockContent: string): string {
+  const trimmedExisting = existingContent.trimEnd();
+  const startIndex = existingContent.indexOf(MANAGED_GUIDANCE_START);
+  const endIndex = existingContent.indexOf(MANAGED_GUIDANCE_END);
+
+  if (startIndex >= 0 || endIndex >= 0) {
+    if (startIndex < 0 || endIndex < 0 || endIndex < startIndex) {
+      throw new Error("Agent guidance target contains malformed Lisa-managed markers.");
+    }
+
+    const suffixIndex = endIndex + MANAGED_GUIDANCE_END.length;
+    return `${existingContent.slice(0, startIndex)}${blockContent}${existingContent.slice(suffixIndex).replace(/^\n*/, "")}`;
+  }
+
+  if (!trimmedExisting) {
+    return blockContent;
+  }
+
+  return `${trimmedExisting}\n\n${blockContent}`;
+}
+
+export function preserveManagedGuidance(existingContent: string, replacementContent: string): string {
+  const startIndex = existingContent.indexOf(MANAGED_GUIDANCE_START);
+  const endIndex = existingContent.indexOf(MANAGED_GUIDANCE_END);
+  if (startIndex < 0 || endIndex < 0 || endIndex < startIndex) {
+    return replacementContent;
+  }
+
+  const block = existingContent.slice(startIndex, endIndex + MANAGED_GUIDANCE_END.length);
+  return upsertManagedGuidance(replacementContent, `${block}\n`);
+}
+
+function resolveGuidanceTargets(config: LoadedSpecWorkspace["config"]): string[] {
+  const guidance = config?.agentGuidance;
+  if (!guidance) {
+    return [];
+  }
+
+  const enabled = guidance.enabled ?? (Boolean(guidance.target) || Boolean(guidance.targets?.length));
+  if (!enabled) {
+    return [];
+  }
+
+  const single = guidance.target?.trim();
+  const plural = guidance.targets?.map((t) => t.trim()).filter((t) => t.length > 0) ?? [];
+  return Array.from(new Set([single, ...plural].filter((t): t is string => Boolean(t))));
+}
+
+function writeGuidanceTarget(workspaceRoot: string, target: string, blockContent: string): string {
+  if (!isSafeRepoRelativePath(target)) {
+    throw new Error(`Spec config agent_guidance target \`${target}\` must stay inside the repository using a safe relative path.`);
+  }
+
+  if (isReservedLisaPath(target)) {
+    throw new Error(`Spec config agent_guidance target \`${target}\` must not point inside \`.specs/\` or \`.lisa/\`.`);
+  }
+
+  const targetPath = resolve(workspaceRoot, target);
+  const relativeTargetPath = normalizeRelativePath(relative(workspaceRoot, targetPath));
+  if (relativeTargetPath === ".." || relativeTargetPath.startsWith("../")) {
+    throw new Error(`Spec config agent_guidance target \`${target}\` must stay inside the repository using a safe relative path.`);
+  }
+
+  assertSafeRepoWritePath(workspaceRoot, targetPath);
+  const existingContent = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
+  if (
+    existingContent
+    && isRootGuidanceTarget(relativeTargetPath || target)
+    && containsLisaSubstring(existingContent)
+    && !existingContent.includes(MANAGED_GUIDANCE_START)
+    && !matchesBundledRootGuidance(relativeTargetPath || target, existingContent)
+  ) {
+    throw new Error(`Refusing to update ${relativeTargetPath || target} because it already contains lisa.`);
+  }
+  const nextContent = upsertManagedGuidance(existingContent, blockContent);
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, nextContent);
+  return relativeTargetPath || target;
+}
+
+export function updateAgentGuidance(workspaceRoot: string): string | undefined {
+  const workspace = loadSpecWorkspace(workspaceRoot);
+  const targets = resolveGuidanceTargets(workspace.config);
+  if (targets.length === 0) {
+    return undefined;
+  }
+
+  const blockContent = renderManagedGuidanceContent(workspace);
+  const written: string[] = [];
+  for (const target of targets) {
+    written.push(writeGuidanceTarget(workspaceRoot, target, blockContent));
+  }
+
+  return written.join(", ");
+}
+
+export function assertSafeRepoWritePath(workspaceRoot: string, targetPath: string): void {
+  const workspaceRealPath = realpathSync(workspaceRoot);
+  let existingPath = targetPath;
+
+  while (!existsSync(existingPath)) {
+    const parentPath = dirname(existingPath);
+    if (parentPath === existingPath) {
+      throw new Error(`Could not resolve a safe parent directory for ${targetPath}`);
+    }
+    existingPath = parentPath;
+  }
+
+  let cursor = existingPath;
+  while (true) {
+    if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink()) {
+      throw new Error(`Refusing to write agent guidance through symlinked path: ${cursor}`);
+    }
+
+    if (cursor === workspaceRoot) {
+      break;
+    }
+
+    const parentPath = dirname(cursor);
+    if (parentPath === cursor) {
+      break;
+    }
+    cursor = parentPath;
+  }
+
+  const realExistingPath = realpathSync(existingPath);
+  if (realExistingPath !== workspaceRealPath && !realExistingPath.startsWith(`${workspaceRealPath}/`)) {
+    throw new Error(`Refusing to write agent guidance outside the repository: ${targetPath}`);
+  }
+
+  if (existsSync(targetPath)) {
+    const realTargetPath = realpathSync(targetPath);
+    if (realTargetPath !== workspaceRealPath && !realTargetPath.startsWith(`${workspaceRealPath}/`)) {
+      throw new Error(`Refusing to overwrite agent guidance outside the repository: ${targetPath}`);
+    }
+  }
+}
+
+export function updateAgentGuidanceSafely(
+  workspaceRoot: string,
+  options: { onlyExistingTargets?: boolean } = {},
+): { path?: string; warning?: string } {
+  try {
+    const workspace = loadSpecWorkspace(workspaceRoot);
+    const targets = resolveGuidanceTargets(workspace.config)
+      .filter((target) => !options.onlyExistingTargets || existsSync(resolve(workspaceRoot, target)));
+    if (targets.length === 0) {
+      return {};
+    }
+
+    const blockContent = renderManagedGuidanceContent(workspace);
+    const written: string[] = [];
+    const warnings: string[] = [];
+
+    for (const target of targets) {
+      try {
+        written.push(writeGuidanceTarget(workspaceRoot, target, blockContent));
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warnings.push(`${target}: ${message}`);
+      }
+    }
+
+    return {
+      path: written.length > 0 ? written.join(", ") : undefined,
+      warning: warnings.length > 0 ? warnings.join("; ") : undefined,
+    };
+  } catch (error) {
+    return {
+      warning: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/spec/cli.ts

@@ -0,0 +1,151 @@
+import { resolveOutputMode } from "../output-mode";
+import { runSpecCheckCommand } from "./commands/check";
+import { runSpecConfigCommand } from "./commands/config";
+import { runSpecDiffCommand } from "./commands/diff";
+import { runSpecGenerateCommand } from "./commands/generate";
+import { runSpecGuideCommand } from "./commands/guide";
+import { runSpecHarnessListCommand } from "./commands/harness-list";
+import { runSpecImportCommand } from "./commands/import";
+import { runSpecImplementCommand } from "./commands/implement";
+import { runSpecInitCommand } from "./commands/init";
+import { runSpecStatusCommand } from "./commands/status";
+
+function printSpecHelp(): void {
+  const outputMode = resolveOutputMode();
+  const interactive = outputMode === "interactive";
+  const intro = interactive
+    ? `Specs in .specs/ define intended behavior. Lisa diffs those specs, plans the work, runs one writer for implementation, and then verifies the result.
+
+Use Lisa spec commands to scaffold the spec workspace, author or import specs, inspect spec deltas, run implementation, and verify conformance.
+
+Workflow:
+  init              Scaffold .specs/ for the repo
+  guide             Create or reuse a seed spec and open the harness skill
+  generate/import   Draft new specs from prompts or existing code
+  diff              Review changed specs and the derived plan
+  implement         Run the single-writer implementation harness
+  check             Verify changed or all specs with tests and reports
+
+Override output mode with LISA_OUTPUT_MODE=interactive or LISA_OUTPUT_MODE=concise.
+
+`
+    : "";
+
+  console.log(`Lisa spec commands
+
+${intro}Usage:
+  lisa spec init
+  lisa spec status
+  lisa spec config [options]
+  lisa spec harness list
+  lisa spec guide [backend|frontend] [name] [options]
+  lisa spec generate [backend|frontend] [name] [options]
+  lisa spec implement [options]
+  lisa spec check --changed|--all [options]
+  lisa spec import <path...> [options]
+  lisa spec diff [options]
+
+Available today:
+  init            Scaffold a .specs workspace for the current repo
+  status          Show spec workspace and harness status
+  config          View or set local harness and model overrides
+  harness list    List registered harness adapters and capabilities
+  guide           Create or reuse a seed spec and point to the right harness skill
+  generate        Draft a spec with preview and approval gates
+  diff            Show changed spec deltas and the derived implementation plan
+  implement       Run a single-writer implementation harness from spec deltas
+  check           Verify changed or all specs with reports and drift warnings
+  import          Draft reviewable specs from existing code paths
+
+Environment:
+  LISA_OUTPUT_MODE=interactive|concise  Override help copy mode
+
+${interactive ? `Typical flow:
+  1. lisa spec init
+     Set up .specs/ and the default harness config.
+  2. lisa spec guide backend <name>
+     Start a seed spec and jump to the matching harness skill.
+  3. lisa spec generate backend <name>
+     Write a new active spec.
+     or lisa spec import <path...>
+     Draft specs from existing code.
+  4. lisa spec diff
+     Preview the spec delta and derived implementation plan.
+  5. lisa spec implement
+     Turn changed specs into code updates with one writer.
+  6. lisa spec check --changed
+     Re-run mapped tests and verifier audits before review.
+` : ""}
+`);
+}
+
+function printHarnessHelp(): void {
+  console.log(`Lisa spec harness commands
+
+Usage:
+  lisa spec harness list
+`);
+}
+
+export async function runSpecCli(args: string[], cwd = process.cwd()): Promise<number> {
+  const [command, subcommand] = args;
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printSpecHelp();
+    return 0;
+  }
+
+  if (command === "status") {
+    return runSpecStatusCommand(args.slice(1), cwd);
+  }
+
+  if (command === "init") {
+    return runSpecInitCommand(args.slice(1), cwd);
+  }
+
+  if (command === "config") {
+    return runSpecConfigCommand(args.slice(1), cwd);
+  }
+
+  if (command === "generate") {
+    return runSpecGenerateCommand(args.slice(1), cwd);
+  }
+
+  if (command === "guide") {
+    return runSpecGuideCommand(args.slice(1), cwd);
+  }
+
+  if (command === "diff") {
+    return runSpecDiffCommand(args.slice(1), cwd);
+  }
+
+  if (command === "implement") {
+    return runSpecImplementCommand(args.slice(1), cwd);
+  }
+
+  if (command === "check") {
+    return runSpecCheckCommand(args.slice(1), cwd);
+  }
+
+  if (command === "import") {
+    return runSpecImportCommand(args.slice(1), cwd);
+  }
+
+  if (command === "harness") {
+    if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+      printHarnessHelp();
+      return 0;
+    }
+
+    if (subcommand === "list") {
+      return runSpecHarnessListCommand(cwd);
+    }
+
+    console.error(`Unknown lisa spec harness command: ${subcommand}`);
+    return 1;
+  }
+
+  console.error(`Unknown lisa spec command: ${command}`);
+  console.error("Run `lisa spec --help` for available commands.");
+  return 1;
+}

package/src/spec/commands/check.ts

@@ -0,0 +1 @@
+export { runSpecCheckCommand } from "../workflows/check";