@wkronmiller/lisa 0.1.0

package/src/spec/workspace.ts

@@ -0,0 +1,541 @@
+import { createHash } from "crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "fs";
+import { dirname, join, resolve, relative } from "path";
+
+import { resolveXdgConfigHome, resolveXdgDataHome, resolveXdgStateHome } from "../skill/artifacts";
+
+export type LisaStorageMode = "repo" | "external";
+export type SpecWriteScope = "repo" | "worktree";
+
+export interface ResolvedWorkspaceLayout {
+  workspacePath: string;
+  storageMode: LisaStorageMode;
+  repoSpecRoot: string;
+  worktreeSpecRoot?: string;
+  runtimeRoot: string;
+  snapshotRoot: string;
+  configPath: string;
+  repoConfigPath: string;
+  worktreeConfigPath?: string;
+  localConfigRoot: string;
+  metadataPath?: string;
+  globalPackRoots: string[];
+}
+
+export interface SpecWorkspaceSnapshot {
+  workspacePath: string;
+  storageMode: LisaStorageMode;
+  rootPath: string;
+  exists: boolean;
+  configPath: string;
+  hasConfig: boolean;
+  backendSpecCount: number;
+  frontendSpecCount: number;
+  benchmarkSpecCount: number;
+  environmentCount: number;
+  repoSpecRoot: string;
+  worktreeSpecRoot?: string;
+  runtimeRoot: string;
+  snapshotRoot: string;
+  metadataPath?: string;
+  globalPackRoots: string[];
+}
+
+interface ExternalWorkspaceMetadata {
+  mode: "external";
+  workspacePath: string;
+  repoIdentityPath: string;
+  worktreeIdentityPath: string;
+  globalPackRoots?: string[];
+}
+
+const BOOTSTRAP_MARKER_FILES = [
+  "package.json",
+  "Cargo.toml",
+  "go.mod",
+  "pyproject.toml",
+  "Makefile",
+  "bunfig.toml",
+  "tsconfig.json",
+] as const;
+
+const BOOTSTRAP_DESCRIPTOR_FILES = [
+  "AGENTS.md",
+  "README.md",
+] as const;
+
+const BOOTSTRAP_MARKER_DIRECTORIES = [
+  "src",
+  "tests",
+  "docs",
+  "scripts",
+  "config",
+  "docker",
+] as const;
+
+function countFiles(path: string, predicate: (entry: string) => boolean): number {
+  if (!existsSync(path)) {
+    return 0;
+  }
+
+  return readdirSync(path).filter(predicate).length;
+}
+
+function decodeOutput(bytes: Uint8Array<ArrayBufferLike>): string {
+  return new TextDecoder().decode(bytes);
+}
+
+function hashPath(path: string): string {
+  return createHash("sha1").update(path).digest("hex");
+}
+
+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 safeRealpath(path: string): string {
+  return existsSync(path) ? realpathSync(path) : resolve(path);
+}
+
+function runGitCommand(cwd: string, args: string[]): { exitCode: number; stdout: string; stderr: string } {
+  const proc = Bun.spawnSync({
+    cmd: ["git", ...args],
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  return {
+    exitCode: proc.exitCode,
+    stdout: decodeOutput(proc.stdout).trim(),
+    stderr: decodeOutput(proc.stderr).trim(),
+  };
+}
+
+function resolveGitCommonDir(workspacePath: string): string | undefined {
+  const result = runGitCommand(workspacePath, ["rev-parse", "--git-common-dir"]);
+  if (result.exitCode !== 0 || result.stdout.length === 0) {
+    return undefined;
+  }
+
+  return resolve(workspacePath, result.stdout);
+}
+
+function resolveRepoIdentityPath(workspacePath: string): string {
+  return safeRealpath(resolveGitCommonDir(workspacePath) ?? workspacePath);
+}
+
+function resolveWorktreeIdentityPath(workspacePath: string): string {
+  return safeRealpath(workspacePath);
+}
+
+function resolveExternalMetadataPath(workspacePath: string): string {
+  const repoId = hashPath(resolveRepoIdentityPath(workspacePath));
+  const worktreeId = hashPath(resolveWorktreeIdentityPath(workspacePath));
+  return join(resolveXdgConfigHome(), "lisa", "workspaces", repoId, `${worktreeId}.json`);
+}
+
+function normalizeGlobalPackRoot(root: string): string {
+  const resolvedRoot = resolve(root);
+  const specRoot = resolvePackSpecRoot(resolvedRoot);
+
+  for (const candidate of [resolvedRoot, specRoot]) {
+    if (!existsSync(candidate)) {
+      continue;
+    }
+
+    try {
+      if (!statSync(candidate).isDirectory()) {
+        continue;
+      }
+      readdirSync(candidate);
+      return resolvedRoot;
+    } catch {
+      throw new Error(`Configured global pack root is not readable: ${root}`);
+    }
+  }
+
+  throw new Error(`Configured global pack root does not exist: ${root}`);
+}
+
+function readExternalWorkspaceMetadata(workspacePath: string): ExternalWorkspaceMetadata | undefined {
+  const metadataPath = resolveExternalMetadataPath(workspacePath);
+  if (!existsSync(metadataPath)) {
+    return undefined;
+  }
+
+  let raw: Partial<ExternalWorkspaceMetadata>;
+  try {
+    raw = JSON.parse(readFileSync(metadataPath, "utf8")) as Partial<ExternalWorkspaceMetadata>;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Malformed Lisa external workspace metadata at ${metadataPath}: ${message}`);
+  }
+
+  if (raw.mode !== "external") {
+    throw new Error(`Unsupported Lisa workspace metadata mode in ${metadataPath}.`);
+  }
+
+  const repoIdentityPath = resolveRepoIdentityPath(workspacePath);
+  if (raw.repoIdentityPath && safeRealpath(raw.repoIdentityPath) !== repoIdentityPath) {
+    throw new Error(`Lisa external workspace metadata at ${metadataPath} does not match this repository.`);
+  }
+
+  const worktreeIdentityPath = resolveWorktreeIdentityPath(workspacePath);
+  if (raw.worktreeIdentityPath && safeRealpath(raw.worktreeIdentityPath) !== worktreeIdentityPath) {
+    throw new Error(`Lisa external workspace metadata at ${metadataPath} does not match this worktree.`);
+  }
+
+  const globalPackRoots = Array.isArray(raw.globalPackRoots)
+    ? raw.globalPackRoots
+      .filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+      .map((entry) => normalizeGlobalPackRoot(entry.trim()))
+    : [];
+  return {
+    mode: "external",
+    workspacePath,
+    repoIdentityPath,
+    worktreeIdentityPath,
+    globalPackRoots,
+  };
+}
+
+function resolveExternalRoots(workspacePath: string, globalPackRoots: string[] = []): ResolvedWorkspaceLayout {
+  const repoIdentityPath = resolveRepoIdentityPath(workspacePath);
+  const worktreeIdentityPath = resolveWorktreeIdentityPath(workspacePath);
+  const repoId = hashPath(repoIdentityPath);
+  const worktreeId = hashPath(worktreeIdentityPath);
+  const repoRoot = join(resolveXdgDataHome(), "lisa", "repos", repoId, "repo");
+  const worktreeRoot = join(resolveXdgStateHome(), "lisa", "worktrees", repoId, worktreeId, "specs");
+  const runtimeRoot = join(resolveXdgStateHome(), "lisa", "worktrees", repoId, worktreeId, "runtime");
+  const snapshotRoot = join(resolveXdgStateHome(), "lisa", "worktrees", repoId, worktreeId, "snapshots");
+  const repoSpecRoot = join(repoRoot, ".specs");
+  const worktreeSpecRoot = join(worktreeRoot, ".specs");
+  const repoConfigPath = join(repoSpecRoot, "config.yaml");
+  const worktreeConfigPath = join(worktreeSpecRoot, "config.yaml");
+
+  return {
+    workspacePath,
+    storageMode: "external",
+    repoSpecRoot,
+    worktreeSpecRoot,
+    runtimeRoot,
+    snapshotRoot,
+    configPath: existsSync(worktreeConfigPath) ? worktreeConfigPath : repoConfigPath,
+    repoConfigPath,
+    worktreeConfigPath,
+    localConfigRoot: runtimeRoot,
+    metadataPath: resolveExternalMetadataPath(workspacePath),
+    globalPackRoots,
+  };
+}
+
+export function resolveWorkspaceRoot(cwd = process.cwd()): string {
+  let current = resolve(cwd);
+
+  while (true) {
+    if (existsSync(join(current, ".git")) || existsSync(join(current, ".specs")) || existsSync(join(current, ".lisa"))) {
+      return current;
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      return cwd;
+    }
+
+    current = parent;
+  }
+}
+
+export function resolveBootstrapWorkspaceRoot(cwd = process.cwd()): string {
+  const target = resolve(cwd);
+  const structureMarkerCount = BOOTSTRAP_MARKER_DIRECTORIES.filter((marker) => existsSync(join(target, marker))).length;
+
+  if (
+    existsSync(join(target, ".git"))
+    || existsSync(join(target, ".specs"))
+    || existsSync(join(target, ".lisa"))
+    || BOOTSTRAP_MARKER_FILES.some((marker) => existsSync(join(target, marker)))
+    || structureMarkerCount >= 2
+    || (structureMarkerCount >= 1 && BOOTSTRAP_DESCRIPTOR_FILES.some((marker) => existsSync(join(target, marker))))
+  ) {
+    return target;
+  }
+
+  return resolveWorkspaceRoot(target);
+}
+
+function resolveRepoWorkspaceLayout(workspacePath: string): ResolvedWorkspaceLayout {
+  const repoSpecRoot = join(workspacePath, ".specs");
+  return {
+    workspacePath,
+    storageMode: "repo",
+    repoSpecRoot,
+    runtimeRoot: join(workspacePath, ".lisa"),
+    snapshotRoot: join(workspacePath, ".lisa", "snapshots"),
+    configPath: join(repoSpecRoot, "config.yaml"),
+    repoConfigPath: join(repoSpecRoot, "config.yaml"),
+    localConfigRoot: repoSpecRoot,
+    globalPackRoots: [],
+  };
+}
+
+export function resolveWorkspaceLayoutFromRoot(workspacePath: string): ResolvedWorkspaceLayout {
+  const resolvedWorkspacePath = resolve(workspacePath);
+  const externalMetadata = readExternalWorkspaceMetadata(resolvedWorkspacePath);
+  if (externalMetadata) {
+    return resolveExternalRoots(resolvedWorkspacePath, externalMetadata.globalPackRoots ?? []);
+  }
+
+  return resolveRepoWorkspaceLayout(resolvedWorkspacePath);
+}
+
+export function resolveWorkspaceLayout(cwd = process.cwd()): ResolvedWorkspaceLayout {
+  return resolveWorkspaceLayoutFromRoot(resolveWorkspaceRoot(cwd));
+}
+
+export function assertSafeLisaStorageWritePath(rootPath: string, targetPath: string, label = "Lisa storage"): void {
+  const resolvedRoot = resolve(rootPath);
+  const resolvedTarget = resolve(targetPath);
+  if (!isPathInsideRoot(resolvedRoot, resolvedTarget)) {
+    throw new Error(`${label} writes must stay inside ${resolvedRoot}.`);
+  }
+
+  let existingRootBoundary = resolvedRoot;
+  while (!existsSync(existingRootBoundary)) {
+    const parentPath = dirname(existingRootBoundary);
+    if (parentPath === existingRootBoundary) {
+      break;
+    }
+    existingRootBoundary = parentPath;
+  }
+
+  const rootRealPath = existsSync(existingRootBoundary) ? realpathSync(existingRootBoundary) : undefined;
+  let existingPath = resolvedTarget;
+  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 (lstatSync(cursor).isSymbolicLink()) {
+      throw new Error(`Refusing to write through symlinked Lisa storage 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(`${label} writes must stay inside ${resolvedRoot}.`);
+  }
+
+  if (existsSync(resolvedTarget)) {
+    const targetRealPath = realpathSync(resolvedTarget);
+    if (!isPathInsideRoot(rootRealPath, targetRealPath)) {
+      throw new Error(`${label} writes must stay inside ${resolvedRoot}.`);
+    }
+  }
+}
+
+function listLayerFiles(path: string, predicate: (entry: string) => boolean): string[] {
+  if (!existsSync(path)) {
+    return [];
+  }
+
+  return readdirSync(path).filter(predicate).sort().map((entry) => join(path, entry));
+}
+
+function resolvePackSpecRoot(root: string): string {
+  return root.endsWith("/.specs") || root.endsWith("\\.specs") ? root : join(root, ".specs");
+}
+
+export function listEffectiveWorkspaceFiles(layout: ResolvedWorkspaceLayout): {
+  configPath?: string;
+  documentPaths: string[];
+  environmentPaths: string[];
+} {
+  if (layout.storageMode === "repo") {
+    return {
+      configPath: existsSync(layout.configPath) ? layout.configPath : undefined,
+      documentPaths: [
+        ...listLayerFiles(join(layout.repoSpecRoot, "backend"), (entry) => entry.endsWith(".md")),
+        ...listLayerFiles(join(layout.repoSpecRoot, "frontend"), (entry) => entry.endsWith(".md")),
+      ],
+      environmentPaths: listLayerFiles(join(layout.repoSpecRoot, "environments"), (entry) => entry.endsWith(".yaml") || entry.endsWith(".yml")),
+    };
+  }
+
+  const layerRoots = [
+    ...layout.globalPackRoots.map((root) => resolvePackSpecRoot(root)),
+    layout.repoSpecRoot,
+    layout.worktreeSpecRoot,
+  ].filter((root): root is string => Boolean(root));
+  const selected = new Map<string, string>();
+
+  for (const layerRoot of layerRoots) {
+    const configPath = join(layerRoot, "config.yaml");
+    if (existsSync(configPath)) {
+      selected.set("config.yaml", configPath);
+    }
+
+    for (const [subdir, matcher] of [
+      ["backend", (entry: string) => entry.endsWith(".md")],
+      ["frontend", (entry: string) => entry.endsWith(".md")],
+      ["environments", (entry: string) => entry.endsWith(".yaml") || entry.endsWith(".yml")],
+    ] as const) {
+      for (const path of listLayerFiles(join(layerRoot, subdir), matcher)) {
+        selected.set(`${subdir}/${relative(join(layerRoot, subdir), path).split("\\").join("/")}`, path);
+      }
+    }
+  }
+
+  return {
+    configPath: selected.get("config.yaml"),
+    documentPaths: Array.from(selected.entries())
+      .filter(([key]) => key.startsWith("backend/") || key.startsWith("frontend/"))
+      .map(([, path]) => path)
+      .sort(),
+    environmentPaths: Array.from(selected.entries())
+      .filter(([key]) => key.startsWith("environments/"))
+      .map(([, path]) => path)
+      .sort(),
+  };
+}
+
+export function resolveEffectiveProjectSpecPath(layout: ResolvedWorkspaceLayout): string | undefined {
+  if (layout.storageMode === "repo") {
+    const projectPath = join(layout.repoSpecRoot, "project.md");
+    return existsSync(projectPath) ? projectPath : undefined;
+  }
+
+  const layerRoots = [
+    ...layout.globalPackRoots.map((root) => resolvePackSpecRoot(root)),
+    layout.repoSpecRoot,
+    layout.worktreeSpecRoot,
+  ].filter((root): root is string => Boolean(root));
+
+  let selected: string | undefined;
+  for (const layerRoot of layerRoots) {
+    const projectPath = join(layerRoot, "project.md");
+    if (existsSync(projectPath)) {
+      selected = projectPath;
+    }
+  }
+
+  return selected;
+}
+
+export function toLogicalPath(layout: ResolvedWorkspaceLayout, targetPath: string): string {
+  const normalizedTarget = resolve(targetPath);
+
+  for (const globalPackRoot of layout.globalPackRoots) {
+    const specRoot = resolve(resolvePackSpecRoot(globalPackRoot));
+    const prefix = `${specRoot}${normalizedTarget === specRoot ? "" : "/"}`;
+    if (normalizedTarget === specRoot || normalizedTarget.startsWith(prefix)) {
+      return join(".specs", relative(specRoot, normalizedTarget)).split("\\").join("/");
+    }
+  }
+
+  const repoPrefix = `${resolve(layout.repoSpecRoot)}${normalizedTarget === resolve(layout.repoSpecRoot) ? "" : "/"}`;
+  if (normalizedTarget === resolve(layout.repoSpecRoot) || normalizedTarget.startsWith(repoPrefix)) {
+    return join(".specs", relative(layout.repoSpecRoot, normalizedTarget)).split("\\").join("/");
+  }
+
+  if (layout.worktreeSpecRoot) {
+    const worktreeRoot = resolve(layout.worktreeSpecRoot);
+    const worktreePrefix = `${worktreeRoot}${normalizedTarget === worktreeRoot ? "" : "/"}`;
+    if (normalizedTarget === worktreeRoot || normalizedTarget.startsWith(worktreePrefix)) {
+      return join(".specs", relative(layout.worktreeSpecRoot, normalizedTarget)).split("\\").join("/");
+    }
+  }
+
+  const runtimeRoot = resolve(layout.runtimeRoot);
+  const runtimePrefix = `${runtimeRoot}${normalizedTarget === runtimeRoot ? "" : "/"}`;
+  if (normalizedTarget === runtimeRoot || normalizedTarget.startsWith(runtimePrefix)) {
+    return join(".lisa", relative(layout.runtimeRoot, normalizedTarget)).split("\\").join("/");
+  }
+
+  return relative(layout.workspacePath, normalizedTarget).split("\\").join("/") || normalizedTarget;
+}
+
+export function resolveSpecWriteRoot(cwd = process.cwd(), scope: SpecWriteScope = "repo"): string {
+  const layout = resolveWorkspaceLayout(cwd);
+  if (layout.storageMode !== "external" || scope === "repo") {
+    return layout.repoSpecRoot;
+  }
+
+  return layout.worktreeSpecRoot ?? layout.repoSpecRoot;
+}
+
+export function initializeExternalWorkspace(cwd = process.cwd(), globalPackRoots: string[] = []): ResolvedWorkspaceLayout {
+  const workspacePath = resolveBootstrapWorkspaceRoot(cwd);
+  const normalizedGlobalPackRoots = globalPackRoots.map((root) => normalizeGlobalPackRoot(root));
+  const layout = resolveExternalRoots(workspacePath, normalizedGlobalPackRoots);
+  const metadata: ExternalWorkspaceMetadata = {
+    mode: "external",
+    workspacePath,
+    repoIdentityPath: resolveRepoIdentityPath(workspacePath),
+    worktreeIdentityPath: resolveWorktreeIdentityPath(workspacePath),
+    globalPackRoots: normalizedGlobalPackRoots,
+  };
+
+  mkdirSync(dirname(layout.metadataPath as string), { recursive: true });
+  mkdirSync(layout.repoSpecRoot, { recursive: true });
+  mkdirSync(layout.worktreeSpecRoot as string, { recursive: true });
+  mkdirSync(layout.runtimeRoot, { recursive: true });
+  mkdirSync(layout.snapshotRoot, { recursive: true });
+  writeFileSync(layout.metadataPath as string, `${JSON.stringify(metadata, null, 2)}\n`);
+  return layout;
+}
+
+export function inspectSpecWorkspace(cwd = process.cwd()): SpecWorkspaceSnapshot {
+  const layout = resolveWorkspaceLayout(cwd);
+  const effective = listEffectiveWorkspaceFiles(layout);
+  const isBaseSpec = (entry: string) => entry.endsWith(".md") && !entry.includes(".bench.");
+  const isBenchmarkSpec = (entry: string) => entry.endsWith(".md") && entry.includes(".bench.");
+
+  return {
+    workspacePath: layout.workspacePath,
+    storageMode: layout.storageMode,
+    rootPath: layout.repoSpecRoot,
+    exists: effective.documentPaths.length > 0 || effective.environmentPaths.length > 0 || existsSync(layout.repoSpecRoot),
+    configPath: layout.configPath,
+    hasConfig: Boolean(effective.configPath),
+    backendSpecCount: effective.documentPaths
+      .filter((path) => toLogicalPath(layout, path).startsWith(".specs/backend/"))
+      .filter(isBaseSpec)
+      .length,
+    frontendSpecCount: effective.documentPaths
+      .filter((path) => toLogicalPath(layout, path).startsWith(".specs/frontend/"))
+      .filter(isBaseSpec)
+      .length,
+    benchmarkSpecCount: effective.documentPaths.filter((path) => isBenchmarkSpec(toLogicalPath(layout, path))).length,
+    environmentCount: effective.environmentPaths.length,
+    repoSpecRoot: layout.repoSpecRoot,
+    worktreeSpecRoot: layout.worktreeSpecRoot,
+    runtimeRoot: layout.runtimeRoot,
+    snapshotRoot: layout.snapshotRoot,
+    metadataPath: layout.metadataPath,
+    globalPackRoots: layout.globalPackRoots,
+  };
+}

package/uninstall.ps1

@@ -0,0 +1,21 @@
+# Uninstall script for Lisa CLI (Windows)
+
+$ErrorActionPreference = "Stop"
+
+Write-Host "Uninstalling Lisa CLI..."
+
+if (Get-Command bun -ErrorAction SilentlyContinue) {
+  Write-Host "Unlinking lisa command (bun)..."
+  bun unlink @wkronmiller/lisa 2>$null
+  bun unlink @th0rgal/lisa 2>$null
+}
+
+if (Get-Command npm -ErrorAction SilentlyContinue) {
+  Write-Host "Removing global package (npm)..."
+  npm uninstall -g @wkronmiller/lisa 2>$null
+  npm uninstall -g @th0rgal/lisa 2>$null
+}
+
+Write-Host ""
+Write-Host "Uninstall complete!"
+Write-Host "You may also want to remove the cloned repository."

package/uninstall.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Uninstall script for Lisa CLI
+
+set -e
+
+echo "Uninstalling Lisa CLI..."
+
+if command -v bun &> /dev/null; then
+  echo "Unlinking lisa command (bun)..."
+  bun unlink @wkronmiller/lisa 2>/dev/null || true
+  bun unlink @th0rgal/lisa 2>/dev/null || true
+fi
+
+if command -v npm &> /dev/null; then
+  echo "Removing global package (npm)..."
+  npm uninstall -g @wkronmiller/lisa 2>/dev/null || true
+  npm uninstall -g @th0rgal/lisa 2>/dev/null || true
+fi
+
+echo ""
+echo "Uninstall complete!"
+echo "You may also want to remove the cloned repository."