supipowers 1.5.2 → 2.0.0

package/src/ultraplan/storage.ts

@@ -0,0 +1,374 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { PlatformPaths } from "../platform/types.js";
+import type {
+  UltraPlanAuthoredArtifact,
+  UltraPlanDomainReview,
+  UltraPlanIndex,
+  UltraPlanManifest,
+  UltraPlanRuntimeTracker,
+  UltraPlanSessionMigrationRecord,
+  UltraPlanSessionSummary,
+  UltraPlanStackId,
+  UltraPlanStackReview,
+  UltraPlanStorageError,
+  UltraPlanStorageResult,
+} from "../types.js";
+import {
+  getUltraPlanSchemaErrors,
+  UltraPlanDomainReviewSchema,
+  UltraPlanStackReviewSchema,
+  validateUltraPlanAuthoredArtifact,
+  validateUltraPlanIndex,
+  validateUltraPlanManifest,
+} from "./contracts.js";
+import {
+  getUltraplanAuthoredJsonPath,
+  getUltraplanDomainReviewPath,
+  getUltraplanIndexPath,
+  getUltraplanManifestPath,
+  getUltraplanSessionDir,
+  getUltraplanStackReviewPath,
+} from "./project-paths.js";
+import {
+  loadMigrationRecord,
+  loadTracker,
+  saveMigrationRecord,
+  saveTrackerAtomic,
+} from "./runtime/tracker-storage.js";
+
+function success<T>(value: T): UltraPlanStorageResult<T> {
+  return { ok: true, value };
+}
+
+function failure(pathname: string, kind: UltraPlanStorageError["kind"], message: string, details?: string[]): UltraPlanStorageResult<never> {
+  return {
+    ok: false,
+    error: {
+      kind,
+      path: pathname,
+      message,
+      ...(details ? { details } : {}),
+    },
+  };
+}
+
+function ensureDir(filePath: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readJsonFile(filePath: string): UltraPlanStorageResult<unknown> {
+  if (!fs.existsSync(filePath)) {
+    return failure(filePath, "missing", `Artifact not found: ${filePath}`);
+  }
+
+  try {
+    return success(JSON.parse(fs.readFileSync(filePath, "utf8")));
+  } catch (error) {
+    return failure(
+      filePath,
+      "invalid-json",
+      error instanceof Error ? error.message : `Invalid JSON in ${filePath}`,
+    );
+  }
+}
+
+function writeJsonFile(filePath: string, payload: unknown): UltraPlanStorageResult<string> {
+  try {
+    ensureDir(filePath);
+    fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`);
+    return success(filePath);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to write ${filePath}`,
+    );
+  }
+}
+
+function resolveSessionArtifactPath(sessionDir: string, artifactPath: string): string {
+  return path.isAbsolute(artifactPath) ? artifactPath : path.join(sessionDir, artifactPath);
+}
+
+function loadValidatedArtifact<T>(
+  filePath: string,
+  validate: (value: unknown) => { ok: true; value: T } | { ok: false; errors: string[] },
+): UltraPlanStorageResult<T> {
+  const parsed = readJsonFile(filePath);
+  if (!parsed.ok) {
+    return parsed;
+  }
+
+  const validation = validate(parsed.value);
+  if (!validation.ok) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, validation.errors);
+  }
+
+  return success(validation.value);
+}
+
+function loadOptionalValidatedArtifact<T>(
+  filePath: string,
+  schemaErrors: (value: unknown) => string[],
+): UltraPlanStorageResult<T | null> {
+  if (!fs.existsSync(filePath)) {
+    return success(null);
+  }
+
+  const parsed = readJsonFile(filePath);
+  if (!parsed.ok) {
+    return parsed;
+  }
+
+  const errors = schemaErrors(parsed.value);
+  if (errors.length > 0) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, errors);
+  }
+
+  return success(parsed.value as T);
+}
+
+export function saveUltraPlanIndex(
+  paths: PlatformPaths,
+  cwd: string,
+  index: UltraPlanIndex,
+): UltraPlanStorageResult<string> {
+  const validation = validateUltraPlanIndex(index);
+  if (!validation.ok) {
+    const filePath = getUltraplanIndexPath(paths, cwd);
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, validation.errors);
+  }
+
+  return writeJsonFile(getUltraplanIndexPath(paths, cwd), validation.value);
+}
+
+export function loadUltraPlanIndex(paths: PlatformPaths, cwd: string): UltraPlanStorageResult<UltraPlanIndex> {
+  const filePath = getUltraplanIndexPath(paths, cwd);
+  if (!fs.existsSync(filePath)) {
+    return failure(filePath, "missing", `Artifact not found: ${filePath}`);
+  }
+
+  return loadValidatedArtifact(filePath, validateUltraPlanIndex);
+}
+
+export function saveUltraPlanManifest(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  manifest: UltraPlanManifest,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanManifestPath(paths, cwd, sessionId);
+  const validation = validateUltraPlanManifest(manifest);
+  if (!validation.ok) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, validation.errors);
+  }
+
+  return writeJsonFile(filePath, validation.value);
+}
+
+export function loadUltraPlanManifest(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<UltraPlanManifest> {
+  return loadValidatedArtifact(getUltraplanManifestPath(paths, cwd, sessionId), validateUltraPlanManifest);
+}
+
+export function saveUltraPlanAuthoredArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  authored: UltraPlanAuthoredArtifact,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanAuthoredJsonPath(paths, cwd, sessionId);
+  const validation = validateUltraPlanAuthoredArtifact(authored);
+  if (!validation.ok) {
+    return failure(filePath, "validation-error", `Artifact failed schema validation: ${filePath}`, validation.errors);
+  }
+
+  return writeJsonFile(filePath, validation.value);
+}
+
+export function loadUltraPlanAuthoredArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<UltraPlanAuthoredArtifact> {
+  return loadValidatedArtifact(getUltraplanAuthoredJsonPath(paths, cwd, sessionId), validateUltraPlanAuthoredArtifact);
+}
+
+export function loadUltraPlanDomainReview(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  stack: UltraPlanStackId,
+  domainId: string,
+): UltraPlanStorageResult<UltraPlanDomainReview | null> {
+  return loadOptionalValidatedArtifact<UltraPlanDomainReview>(
+    getUltraplanDomainReviewPath(paths, cwd, sessionId, stack, domainId),
+    (value) => getUltraPlanSchemaErrors(UltraPlanDomainReviewSchema, value),
+  );
+}
+
+export function loadUltraPlanStackReview(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  stack: UltraPlanStackId,
+): UltraPlanStorageResult<UltraPlanStackReview | null> {
+  return loadOptionalValidatedArtifact<UltraPlanStackReview>(
+    getUltraplanStackReviewPath(paths, cwd, sessionId, stack),
+    (value) => getUltraPlanSchemaErrors(UltraPlanStackReviewSchema, value),
+  );
+}
+
+function validatePassedReviewReference(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  review: UltraPlanManifest["reviews"][number],
+): UltraPlanStorageResult<null> {
+  if (review.status !== "passed") {
+    return success(null);
+  }
+
+  const sessionDir = getUltraplanSessionDir(paths, cwd, sessionId);
+  const referencedPath = resolveSessionArtifactPath(sessionDir, review.path);
+
+  if (review.type === "domain") {
+    if (!review.domainId) {
+      return failure(referencedPath, "validation-error", "Passed domain review reference is missing a domainId");
+    }
+
+    const expectedPath = getUltraplanDomainReviewPath(paths, cwd, sessionId, review.stack, review.domainId);
+    if (referencedPath !== expectedPath) {
+      return failure(referencedPath, "validation-error", `Passed domain review reference points at an unexpected artifact path: ${referencedPath}`);
+    }
+
+    const domainReview = loadUltraPlanDomainReview(paths, cwd, sessionId, review.stack, review.domainId);
+    if (!domainReview.ok) {
+      return domainReview;
+    }
+    if (!domainReview.value) {
+      return failure(expectedPath, "missing", `Passed domain review reference is missing review artifact: ${expectedPath}`);
+    }
+    if (domainReview.value.status !== "passed" || domainReview.value.stack !== review.stack || domainReview.value.domainId !== review.domainId) {
+      return failure(expectedPath, "validation-error", `Passed domain review reference does not match the validated review artifact: ${expectedPath}`);
+    }
+
+    return success(null);
+  }
+
+  if (review.domainId !== null) {
+    return failure(referencedPath, "validation-error", "Stack review references must not include a domainId");
+  }
+
+  const expectedPath = getUltraplanStackReviewPath(paths, cwd, sessionId, review.stack);
+  if (referencedPath !== expectedPath) {
+    return failure(referencedPath, "validation-error", `Passed stack review reference points at an unexpected artifact path: ${referencedPath}`);
+  }
+
+  const stackReview = loadUltraPlanStackReview(paths, cwd, sessionId, review.stack);
+  if (!stackReview.ok) {
+    return stackReview;
+  }
+  if (!stackReview.value) {
+    return failure(expectedPath, "missing", `Passed stack review reference is missing review artifact: ${expectedPath}`);
+  }
+  if (stackReview.value.status !== "passed" || stackReview.value.stack !== review.stack) {
+    return failure(expectedPath, "validation-error", `Passed stack review reference does not match the validated review artifact: ${expectedPath}`);
+  }
+
+  return success(null);
+}
+
+export function validateUltraPlanManifestReviewReferences(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  manifest: UltraPlanManifest,
+ ): UltraPlanStorageResult<null> {
+  for (const review of manifest.reviews) {
+    const reviewValidation = validatePassedReviewReference(paths, cwd, sessionId, review);
+    if (!reviewValidation.ok) {
+      return reviewValidation;
+    }
+  }
+
+  return success(null);
+}
+
+
+export function loadUltraPlanSessionSummary(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<UltraPlanSessionSummary> {
+  const manifest = loadUltraPlanManifest(paths, cwd, sessionId);
+  if (!manifest.ok) {
+    return manifest;
+  }
+  const manifestValue = manifest.value;
+  const reviewValidation = validateUltraPlanManifestReviewReferences(paths, cwd, sessionId, manifestValue);
+  if (!reviewValidation.ok) {
+    return reviewValidation;
+  }
+
+  return success({
+    sessionId: manifestValue.sessionId,
+    projectName: manifestValue.projectName,
+    title: manifestValue.title,
+    state: manifestValue.state,
+    createdAt: manifestValue.createdAt,
+    updatedAt: manifestValue.updatedAt,
+    cursor: manifestValue.cursor,
+    lastCompleted: manifestValue.lastCompleted,
+    blocker: manifestValue.blocker,
+    progress: manifestValue.progress,
+    stacks: manifestValue.stacks,
+    reviews: manifestValue.reviews,
+  });
+}
+
+
+// ---------------------------------------------------------------------------
+// Runtime tracker + migration record wrappers (Slice 2 / 1.4).
+// These delegate to `runtime/tracker-storage.ts` so the storage module stays
+// the single public entry point for session-level persistence while the tracker
+// module owns durability details.
+// ---------------------------------------------------------------------------
+
+export function saveUltraPlanRuntimeTracker(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  tracker: UltraPlanRuntimeTracker,
+): UltraPlanStorageResult<string> {
+  return saveTrackerAtomic(paths, cwd, sessionId, tracker);
+}
+
+export function loadUltraPlanRuntimeTracker(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<UltraPlanRuntimeTracker> {
+  return loadTracker(paths, cwd, sessionId);
+}
+
+export function saveUltraPlanSessionMigrationRecord(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  record: UltraPlanSessionMigrationRecord,
+): UltraPlanStorageResult<string> {
+  return saveMigrationRecord(paths, cwd, sessionId, record);
+}
+
+export function loadUltraPlanSessionMigrationRecord(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<UltraPlanSessionMigrationRecord> {
+  return loadMigrationRecord(paths, cwd, sessionId);
+}

package/src/utils/editor.ts

@@ -0,0 +1,38 @@
+import type { Platform } from "../platform/types.js";
+
+/**
+ * Open a file in the user's preferred editor and wait for the editor to exit.
+ *
+ * Resolution order:
+ *  1. `$VISUAL`
+ *  2. `$EDITOR`
+ *  3. OS default opener (`open` on darwin, `start` on win32, `xdg-open` elsewhere)
+ *
+ * `platform.exec` blocks until the spawned editor process exits, which is what
+ * the synthesize stage needs for its `$EDITOR` round-trip. For OS-default openers
+ * on darwin and linux, the spawned process returns immediately — callers that
+ * need true blocking behavior on save must set `$VISUAL` or `$EDITOR` explicitly
+ * (which is the documented requirement for the synth round-trip).
+ *
+ * Errors are non-fatal — if the editor can't be launched, the function returns
+ * without throwing. Callers that need to verify the user actually edited the file
+ * should detect changes by comparing mtime / contents before and after.
+ */
+export async function openInEditor(platform: Platform, filePath: string): Promise<void> {
+  const editor = process.env.VISUAL || process.env.EDITOR;
+  try {
+    if (editor) {
+      // Tokenize on whitespace so users can set EDITOR="code --wait" etc.
+      const tokens = editor.split(/\s+/).filter((t) => t.length > 0);
+      const cmd = tokens[0];
+      const args = [...tokens.slice(1), filePath];
+      await platform.exec(cmd, args);
+    } else {
+      const cmd = process.platform === "darwin" ? "open"
+        : process.platform === "win32" ? "start" : "xdg-open";
+      await platform.exec(cmd, [filePath]);
+    }
+  } catch {
+    // Editor open failed — non-fatal, file was still written
+  }
+}

package/src/utils/executable.ts

@@ -0,0 +1,80 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const DEFAULT_WINDOWS_EXECUTABLE_EXTENSIONS = [".exe", ".cmd", ".bat", ""];
+const POSIX_EXECUTABLE_EXTENSIONS = [""];
+
+export interface ExecutableSearchOptions {
+  cwd?: string;
+  localDirs?: string[];
+  preferLocal?: boolean;
+  searchPath?: string;
+  pathext?: string;
+}
+
+function windowsExecutableExtensions(pathext?: string): string[] {
+  const ordered = (pathext ?? process.env.PATHEXT ?? "")
+    .split(";")
+    .map((ext) => ext.trim())
+    .filter(Boolean)
+    .map((ext) => (ext.startsWith(".") ? ext.toLowerCase() : `.${ext.toLowerCase()}`));
+
+  return [...new Set([...ordered, ...DEFAULT_WINDOWS_EXECUTABLE_EXTENSIONS])];
+}
+
+function executableExtensions(options: ExecutableSearchOptions): string[] {
+  return process.platform === "win32"
+    ? windowsExecutableExtensions(options.pathext)
+    : POSIX_EXECUTABLE_EXTENSIONS;
+}
+
+function isFile(filePath: string): boolean {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function resolveSearchDirectories(options: ExecutableSearchOptions): string[] {
+  const pathDirs = (options.searchPath ?? process.env.PATH ?? "")
+    .split(path.delimiter)
+    .filter(Boolean);
+  const localDirs = (options.localDirs ?? []).map((dir) =>
+    options.cwd ? path.join(options.cwd, dir) : dir,
+  );
+
+  return options.preferLocal
+    ? [...localDirs, ...pathDirs]
+    : [...pathDirs, ...localDirs];
+}
+
+export function findExecutable(
+  executable: string,
+  options: ExecutableSearchOptions = {},
+): string | null {
+  const seen = new Set<string>();
+  const extensions = executableExtensions(options);
+
+  for (const directory of resolveSearchDirectories(options)) {
+    for (const extension of extensions) {
+      const candidate = path.join(directory, `${executable}${extension}`);
+      if (seen.has(candidate)) {
+        continue;
+      }
+      seen.add(candidate);
+      if (isFile(candidate)) {
+        return candidate;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function hasExecutable(
+  executable: string,
+  options: ExecutableSearchOptions = {},
+): boolean {
+  return findExecutable(executable, options) !== null;
+}

package/src/utils/paths.ts

@@ -8,9 +8,7 @@ import * as path from "node:path";
  * The naive alternative — `path.dirname(new URL(import.meta.url).pathname)` —
  * is broken on Windows: `URL.pathname` for a `file:///C:/foo/bar.ts` URL
  * yields `/C:/foo/bar.ts` (leading slash before the drive letter), which
- * `path.dirname` on Windows converts to a backslash path. Those backslashes,
- * when later embedded in a bash command, are consumed as escape sequences and
- * silently corrupt the path.
+ * `path.dirname` on Windows converts to a backslash path.
  *
  * `fileURLToPath` handles the Windows case correctly, stripping the leading
  * slash and returning a proper `C:\foo\bar.ts` path.
@@ -20,20 +18,3 @@ import * as path from "node:path";
 export function moduleDir(importMetaUrl: string): string {
   return path.dirname(fileURLToPath(importMetaUrl));
 }
-
-/**
- * Normalizes path separators to forward slashes so the path is safe to embed
- * in bash commands or shell-script arguments on Windows.
- *
- * Git Bash (and WSL) on Windows interpret `\` as an escape character, so a
- * native Windows path like `C:\Users\foo\bar` silently becomes `C:Usersfoobar`
- * when passed as a bash argument. Forward slashes are accepted by both Git
- * Bash and Node.js file APIs on Windows, so this conversion is safe to apply
- * universally.
- *
- * Use on every path that will be passed to `platform.exec("bash", [...])` or
- * embedded as a literal in an AI prompt that contains bash commands.
- */
-export function toBashPath(p: string): string {
-  return p.replace(/\\/g, "/");
-}

package/src/utils/shell.ts

@@ -0,0 +1,31 @@
+import type { ExecOptions, ExecResult } from "../platform/types.js";
+
+export interface ShellInvocation {
+  command: string;
+  args: string[];
+}
+
+export function getShellInvocation(command: string): ShellInvocation {
+  if (process.platform === "win32") {
+    return { command: "cmd", args: ["/d", "/s", "/c", command] };
+  }
+
+  return { command: "sh", args: ["-lc", command] };
+}
+
+export function createExecShell(
+  exec: (cmd: string, args: string[], opts?: ExecOptions) => Promise<ExecResult>,
+): (command: string, opts?: ExecOptions) => Promise<ExecResult> {
+  return async (command: string, opts?: ExecOptions): Promise<ExecResult> => {
+    const shell = getShellInvocation(command);
+    return exec(shell.command, shell.args, opts);
+  };
+}
+
+export async function execShellCommand(
+  exec: (cmd: string, args: string[], opts?: ExecOptions) => Promise<ExecResult>,
+  command: string,
+  opts?: ExecOptions,
+): Promise<ExecResult> {
+  return createExecShell(exec)(command, opts);
+}

package/src/visual/companion.ts

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 import type { VisualServerInfo, VisualEvent } from "./types.js";
 import { normalizeLineEndings } from "../text.js";
 import type { PlatformPaths } from "../platform/types.js";
+import { getProjectStatePath } from "../workspace/state-paths.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -18,7 +19,7 @@ export function generateVisualSessionId(): string {
 
 /** Create the session directory and return its path */
 export function createSessionDir(paths: PlatformPaths, cwd: string, sessionId: string): string {
-  const sessionDir = paths.project(cwd, "visual", sessionId);
+  const sessionDir = getProjectStatePath(paths, cwd, "visual", sessionId);
   fs.mkdirSync(sessionDir, { recursive: true });
   return sessionDir;
 }

package/src/visual/scripts/frame-template.html

@@ -179,6 +179,66 @@
     .mock-content { padding: 1.5rem; flex: 1; }
     .mock-button { background: var(--accent); color: white; border: none; padding: 0.5rem 1rem; border-radius: 6px; font-size: 0.85rem; }
     .mock-input { background: var(--bg-primary); border: 1px solid var(--border); border-radius: 6px; padding: 0.5rem; width: 100%; }
+
+    /* ===== UI-DESIGN COMPANION ===== */
+    .component-gallery {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+      gap: 1rem;
+      margin: 1rem 0;
+    }
+    .component-gallery .component-tile {
+      background: var(--bg-secondary);
+      border: 1px solid var(--border);
+      border-radius: 10px;
+      overflow: hidden;
+    }
+    .component-gallery .component-tile-header {
+      background: var(--bg-tertiary);
+      padding: 0.5rem 0.75rem;
+      font-size: 0.75rem;
+      color: var(--text-secondary);
+      border-bottom: 1px solid var(--border);
+    }
+    .component-gallery .component-tile-body { padding: 1rem; }
+
+    .preview-grid {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 1rem;
+      margin: 1rem 0;
+    }
+    @media (max-width: 800px) { .preview-grid { grid-template-columns: 1fr; } }
+    .preview-grid > .preview-item {
+      background: var(--bg-secondary);
+      border: 1px solid var(--border);
+      border-radius: 10px;
+      padding: 1rem;
+    }
+
+    .critique-report { display: flex; flex-direction: column; gap: 1rem; margin: 1rem 0; }
+    .critique-report .critique-section {
+      background: var(--bg-secondary);
+      border: 1px solid var(--border);
+      border-radius: 10px;
+      padding: 1rem 1.25rem;
+    }
+    .critique-report .critique-section h3 {
+      font-size: 0.95rem;
+      margin-bottom: 0.5rem;
+    }
+    .critique-report .critique-section.fixable h3 { color: var(--warning); }
+    .critique-report .critique-section.advisory h3 { color: var(--text-secondary); }
+
+    .decomposition-tree {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-size: 0.85rem;
+      background: var(--bg-secondary);
+      border: 1px solid var(--border);
+      border-radius: 10px;
+      padding: 1rem 1.25rem;
+      white-space: pre-wrap;
+    }
   </style>
 </head>
 <body>