elanous 0.2.0 → 0.2.5

package/src/virtual-windows/layout/persistence.ts

@@ -1,219 +0,0 @@
-// ── VW-term-infra Phase 3a — LayoutSpec persistence ──
-//
-// Save / load / list LayoutSpec files under ~/.elanous/layouts/. Each file
-// is one JSON-serialized LayoutSpec. Filenames derive from the
-// caller-provided slug (windowId-label fallback); the slug is sanitized
-// so a hostile spec can never write outside the layouts directory
-// (../foo → foo, slashes → '-', ...).
-//
-// Design:
-//   - Storage root is `~/.elanous/layouts/` by default but overridable via
-//     `LayoutPersistenceOpts.dir` so tests can sandbox into tmp.
-//   - Unknown files (wrong extension, unreadable JSON) are skipped with
-//     a captured `skipped` entry in list() output rather than failing
-//     the whole enumeration — UI layers can surface "broken preset"
-//     toasts without the session falling over.
-//   - Writes are atomic via `tmp-file + rename` so crash during save
-//     leaves the prior version intact.
-//
-// See: 내부 문서 `PLAN-session-vw-term-infra-p3-p5` §3.5
-
-import { constants, promises as fsp } from 'node:fs';
-import { elanousStateRoot } from '../../autopilot/state-paths.js';
-import { join, resolve } from 'node:path';
-
-import { debug } from '../../debug/log.js';
-import type { ArtifactStore } from '../../artifact/index.js';
-import { fromJson, toJson } from './serializer.js';
-import { LayoutSpecValidationError, type LayoutSpec } from './types.js';
-
-export interface LayoutPersistenceOpts {
-  /** Absolute directory. Defaults to ~/.elanous/layouts/. Tests override. */
-  readonly dir?: string;
-}
-
-export interface SavedLayoutListing {
-  readonly slug: string;
-  readonly path: string;
-  readonly spec: LayoutSpec;
-}
-
-export interface SkippedLayoutListing {
-  readonly slug: string;
-  readonly path: string;
-  readonly reason: string;
-}
-
-export interface LayoutListResult {
-  readonly loaded: readonly SavedLayoutListing[];
-  readonly skipped: readonly SkippedLayoutListing[];
-}
-
-const LAYOUT_EXT = '.layout.json';
-
-/** The effective layouts directory. Exported so callers that want to
- *  open the folder in a file browser can stat/mkdirp. */
-export function layoutsDir(opts?: LayoutPersistenceOpts): string {
-  return opts?.dir ?? join(elanousStateRoot(), 'layouts');
-}
-
-/** Slugify an arbitrary label into a filename-safe token.
- *  Deterministic — same input always yields the same slug so
- *  overwriting a named preset works. */
-export function slugify(raw: string): string {
-  if (!raw) return 'unnamed';
-  const ascii = raw
-    .trim()
-    .toLowerCase()
-    .replace(/[\\/:]+/g, '-')     // path separators + colon → dash
-    .replace(/\s+/g, '-')         // whitespace → dash
-    .replace(/[^a-z0-9_\-.]+/g, '') // drop anything else
-    .replace(/-{2,}/g, '-');      // collapse consecutive dashes
-  // Strip leading dots / dashes so we don't produce hidden files or
-  // accidental relative paths.
-  const trimmed = ascii.replace(/^[.\-]+/, '').replace(/[.\-]+$/, '');
-  return trimmed.length > 0 ? trimmed.slice(0, 64) : 'unnamed';
-}
-
-/** Compute a save slug for a spec. Prefers label, falls back to windowId. */
-export function specSlug(spec: LayoutSpec): string {
-  return slugify(spec.label && spec.label.length > 0 ? spec.label : spec.windowId);
-}
-
-export interface SaveLayoutSpecOpts extends LayoutPersistenceOpts {
-  readonly slug?: string;
-  /** Bundle B-5 (P6-4) — unified artifact persistence. When provided,
-   *  the layout body is stored via `store.put('layout', ...)` under
-   *  `~/.elanous/artifacts/layout/` and the returned path points there
-   *  instead of the legacy `~/.elanous/layouts/` directory. Legacy path
-   *  is still the fallback when `artifactStore` is absent (hermetic
-   *  tests + any caller without store DI). */
-  readonly artifactStore?: ArtifactStore;
-}
-
-export async function saveLayoutSpec(
-  spec: LayoutSpec,
-  opts?: SaveLayoutSpecOpts,
-): Promise<string> {
-  const slug = slugify(opts?.slug ?? specSlug(spec));
-  const body = toJson(spec, true);
-
-  // Bundle B-5 · unified artifact store path (preferred).
-  if (opts?.artifactStore) {
-    const handle = opts.artifactStore.put('layout', body, {
-      origin: slug,
-      producer: 'vwt-3a',
-      description: spec.label ?? `Layout for window ${spec.windowId}`,
-      tags: ['layout', `window-${spec.windowId}`],
-    });
-    if (debug.enabled) {
-      debug.log('layout.persistence.save.artifact', slug, {
-        path: handle.path,
-        bytes: body.length,
-      });
-    }
-    return handle.path;
-  }
-
-  // Legacy fallback — `~/.elanous/layouts/<slug>.layout.json` atomic write.
-  const dir = layoutsDir(opts);
-  await fsp.mkdir(dir, { recursive: true });
-  const finalPath = resolve(dir, `${slug}${LAYOUT_EXT}`);
-  const tmpPath = `${finalPath}.tmp.${process.pid}`;
-  await fsp.writeFile(tmpPath, body, 'utf8');
-  await fsp.rename(tmpPath, finalPath);
-  if (debug.enabled) {
-    debug.log('layout.persistence.save', slug, { path: finalPath, bytes: body.length });
-  }
-  return finalPath;
-}
-
-export async function loadLayoutSpec(
-  slug: string,
-  opts?: LayoutPersistenceOpts,
-): Promise<LayoutSpec> {
-  const dir = layoutsDir(opts);
-  const safeSlug = slugify(slug);
-  const path = resolve(dir, `${safeSlug}${LAYOUT_EXT}`);
-  const body = await fsp.readFile(path, 'utf8');
-  return fromJson(body);
-}
-
-/** Bundle B-6 (P6-5) — direct-path loader. Accepts an absolute
- *  artifact path returned by `ListArtifacts({kind:'layout'})` and
- *  reads the spec without slug inference. Caller is responsible for
- *  path validation (e.g. via ArtifactStore.list()). */
-export async function loadLayoutSpecFromPath(absPath: string): Promise<LayoutSpec> {
-  const body = await fsp.readFile(absPath, 'utf8');
-  return fromJson(body);
-}
-
-/** Bundle B-6 (P6-5) — slug-to-artifact resolution. Scans the store's
- *  `layout` kind for an entry whose `meta.origin === slug` · returns
- *  the newest by `createdAt` · returns `null` when no match (caller
- *  falls back to the legacy `~/.elanous/layouts/<slug>.layout.json`
- *  path). Store-native resolution preferred for LLM-supplied slugs
- *  since the artifact path carries a timestamp prefix that makes
- *  direct file access ambiguous. */
-export function resolveLayoutArtifactPath(
-  slug: string,
-  store: import('../../artifact/index.js').ArtifactStore,
-): string | null {
-  const safeSlug = slugify(slug);
-  const listings = store.list('layout');
-  const matching = listings.filter((l) => l.meta.origin === safeSlug);
-  if (matching.length === 0) return null;
-  // list() already sorts by createdAt ascending — pick the last entry
-  // (newest) when the slug has multiple versions.
-  return matching[matching.length - 1]!.path;
-}
-
-export async function listLayoutSpecs(
-  opts?: LayoutPersistenceOpts,
-): Promise<LayoutListResult> {
-  const dir = layoutsDir(opts);
-  try {
-    await fsp.access(dir, constants.R_OK);
-  } catch {
-    return { loaded: [], skipped: [] };
-  }
-  const entries = await fsp.readdir(dir);
-  const loaded: SavedLayoutListing[] = [];
-  const skipped: SkippedLayoutListing[] = [];
-  for (const entry of entries) {
-    if (!entry.endsWith(LAYOUT_EXT)) continue;
-    const path = resolve(dir, entry);
-    const slug = entry.slice(0, -LAYOUT_EXT.length);
-    try {
-      const body = await fsp.readFile(path, 'utf8');
-      const spec = fromJson(body);
-      loaded.push({ slug, path, spec });
-    } catch (err) {
-      const reason = err instanceof LayoutSpecValidationError
-        ? err.message
-        : `read error: ${String(err)}`;
-      skipped.push({ slug, path, reason });
-      if (debug.enabled) debug.log('layout.persistence.skip', slug, { reason });
-    }
-  }
-  // Sort by createdAt desc so newest shows first — UI layers pick that
-  // order for "recent layouts" lists.
-  loaded.sort((a, b) => b.spec.createdAt - a.spec.createdAt);
-  return { loaded, skipped };
-}
-
-export async function deleteLayoutSpec(
-  slug: string,
-  opts?: LayoutPersistenceOpts,
-): Promise<boolean> {
-  const dir = layoutsDir(opts);
-  const safeSlug = slugify(slug);
-  const path = resolve(dir, `${safeSlug}${LAYOUT_EXT}`);
-  try {
-    await fsp.unlink(path);
-    if (debug.enabled) debug.log('layout.persistence.delete', safeSlug, { path });
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/virtual-windows/layout/presets.ts

@@ -1,114 +0,0 @@
-// ── VW-term-infra Phase 3a — Built-in LayoutSpec presets ──
-//
-// Three canonical starting layouts. Embedded as code rather than JSON
-// files so tests don't depend on disk I/O to verify their shape.
-// Consumers that want the presets on disk (shareable, user-editable)
-// can write the result of `buildPreset(...)` to `~/.elanous/layouts/`
-// via `saveLayoutSpec`.
-//
-// Naming: presets reserve `preset-` as a label prefix so a user saving
-// `one-pane` later won't collide with the built-in. `buildPreset()`
-// stamps label + createdAt + windowId on each call so the same preset
-// can be applied to multiple windows.
-//
-// See: 내부 문서 `PLAN-session-vw-term-infra-p3-p5` §3.5 · ~/.elanous/layouts/presets/
-
-import { LAYOUT_SPEC_VERSION, type LayoutSpec, type LayoutSpecNode } from './types.js';
-
-export type LayoutPresetName =
-  | 'one-pane'
-  | 'two-pane-split'
-  | 'three-pane-split'
-  | 'four-pane-kanban';
-
-export const LAYOUT_PRESET_NAMES: readonly LayoutPresetName[] = [
-  'one-pane',
-  'two-pane-split',
-  'three-pane-split',
-  'four-pane-kanban',
-];
-
-interface BuildPresetOpts {
-  /** Virtual-window id the preset binds to. */
-  readonly windowId: string;
-  /** Pane ids to assign to leaves. Must match the preset arity
-   *  (1 / 2 / 4). Preset order: row-first, col-first. */
-  readonly paneIds: readonly string[];
-  /** Clock injection for deterministic tests. */
-  readonly now?: () => number;
-}
-
-export function buildPreset(name: LayoutPresetName, opts: BuildPresetOpts): LayoutSpec {
-  const arity = presetArity(name);
-  if (opts.paneIds.length !== arity) {
-    throw new Error(
-      `buildPreset("${name}"): expected ${arity} pane ids, got ${opts.paneIds.length}`,
-    );
-  }
-  const now = (opts.now ?? Date.now)();
-  const root = buildPresetRoot(name, opts.windowId, opts.paneIds);
-  return {
-    version: LAYOUT_SPEC_VERSION,
-    windowId: opts.windowId,
-    createdAt: now,
-    label: `preset-${name}`,
-    root,
-  };
-}
-
-export function presetArity(name: LayoutPresetName): number {
-  switch (name) {
-    case 'one-pane':         return 1;
-    case 'two-pane-split':   return 2;
-    case 'three-pane-split': return 3;
-    case 'four-pane-kanban': return 4;
-  }
-}
-
-function buildPresetRoot(
-  name: LayoutPresetName,
-  windowId: string,
-  paneIds: readonly string[],
-): LayoutSpecNode {
-  const leaf = (id: string): LayoutSpecNode => ({
-    kind: 'leaf',
-    paneRef: { windowId, paneId: id },
-  });
-  switch (name) {
-    case 'one-pane':
-      return leaf(paneIds[0]!);
-    case 'two-pane-split':
-      return {
-        kind: 'split',
-        axis: 'col',
-        children: [leaf(paneIds[0]!), leaf(paneIds[1]!)],
-        sizes: [0.5, 0.5],
-      };
-    case 'three-pane-split':
-      // Three columns of equal width. Used by H6 P4 `/agent-room 3`
-      // as plan | exec | review side-by-side.
-      return {
-        kind: 'split',
-        axis: 'col',
-        children: [
-          leaf(paneIds[0]!),
-          leaf(paneIds[1]!),
-          leaf(paneIds[2]!),
-        ],
-        sizes: [1 / 3, 1 / 3, 1 / 3],
-      };
-    case 'four-pane-kanban':
-      // Four columns of equal width. Kanban-style: ToDo / Doing / Review / Done.
-      return {
-        kind: 'split',
-        axis: 'col',
-        children: [
-          leaf(paneIds[0]!),
-          leaf(paneIds[1]!),
-          leaf(paneIds[2]!),
-          leaf(paneIds[3]!),
-        ],
-        sizes: [0.25, 0.25, 0.25, 0.25],
-      };
-  }
-}

package/src/virtual-windows/layout/restore-planner.ts

@@ -1,223 +0,0 @@
-// ── VW-term-infra Phase 3a — LayoutSpec restore planner ──
-//
-// Pure planner that turns a persisted `LayoutSpec` into a step-by-step
-// plan for reconstructing the VW runtime. Isolates the decision-making
-// (which panes are available, what falls back) from the side-effectful
-// mount/spawn work that the dashboard owns — keeps substrate code free
-// of UI lifecycle coupling per LESSONS L5.
-//
-// The planner does NOT:
-//   - Spawn panes (caller provides `availablePaneIds` snapshot)
-//   - Mount binary trees into the registry
-//   - Persist restore decisions
-//
-// It DOES:
-//   - Walk the spec tree, resolve each leaf's PaneRef against the
-//     available set, and record missing panes
-//   - Lower split nodes to binary chains (delegating to `toBinaryTree`
-//     via per-subtree conversion when the whole subtree is realizable)
-//   - Skip tabs/float nodes, collecting them as `unsupported` so the
-//     caller can render them elsewhere (tab bar, popover) once Phase 3b
-//     SurfaceRole lands
-//   - Produce a placeholder pane-id substitution for missing leaves
-//     when the caller opts into placeholder-on-missing mode
-//
-// See: 내부 문서 `PLAN-session-vw-term-infra-p3-p5` §3.5 (C12 restore) ·
-//      내부 문서 `CAPABILITIES-vw-layout-spec` §7
-
-import type { Rect } from '../../display/rect.js';
-import type { PaneRef } from '../../panes/types.js';
-import type { LayoutNode as BinaryLayoutNode } from '../layout-tree.js';
-import { fromBinaryTree, toBinaryTree } from './tree.js';
-import { LayoutSpecValidationError, type LayoutSpec, type LayoutSpecNode } from './types.js';
-
-/** Inputs that shape the restore decision. */
-export interface RestorePlanInput {
-  readonly spec: LayoutSpec;
-  /** PaneIds the caller can definitely re-attach right now. Usually the
-   *  union of existing VW pane registrations + whatever the caller is
-   *  about to spawn. Missing leaves are listed in `missing` so the
-   *  caller can decide to spawn, skip, or substitute. */
-  readonly availablePaneIds: ReadonlySet<string>;
-  /** When true, missing leaves are kept in the binary tree using the
-   *  same paneId as the spec called out — the caller's composer is
-   *  expected to render a placeholder pane for unknown ids. When false
-   *  (default), missing leaves are omitted from the tree and reported
-   *  solely in `missing`; split nodes with zero surviving children
-   *  collapse and their siblings' sizes re-normalize. */
-  readonly keepMissingAsPlaceholder?: boolean;
-}
-
-/** What the planner produces. Everything is immutable, so the caller
- *  can examine the plan, ask the user for confirmation, then act. */
-export interface RestorePlan {
-  /** The binary tree ready to hand to the VW runtime registry.
-   *  `null` when the entire spec reduced to unsupported/missing and
-   *  no runnable subtree remains. */
-  readonly binaryRoot: BinaryLayoutNode | null;
-  /** PaneRefs the spec calls out that were not in availablePaneIds. */
-  readonly missing: readonly PaneRef[];
-  /** Tabs containers encountered. Caller renders these via tab-bar
-   *  widget (Phase 3b). Empty until LayoutSpec authors start using
-   *  the tabs kind. */
-  readonly tabs: readonly TabsPlanEntry[];
-  /** Float containers encountered. Caller renders these via popover
-   *  surface (Phase 3b). Empty for today's preset library. */
-  readonly floats: readonly FloatPlanEntry[];
-  /** Non-fatal diagnostics captured during planning. */
-  readonly notes: readonly string[];
-}
-
-export interface TabsPlanEntry {
-  readonly panes: readonly PaneRef[];
-  readonly active: number;
-}
-
-export interface FloatPlanEntry {
-  readonly pane: PaneRef;
-  readonly rect: Rect;
-}
-
-/** Plan the restore of a LayoutSpec against the currently-available
- *  pane population. Pure; throws only on structurally invalid specs
- *  that slipped past `validateSpec` (adapter bugs, not user error). */
-export function planRestore(input: RestorePlanInput): RestorePlan {
-  const missing: PaneRef[] = [];
-  const tabs: TabsPlanEntry[] = [];
-  const floats: FloatPlanEntry[] = [];
-  const notes: string[] = [];
-  const keepMissing = input.keepMissingAsPlaceholder === true;
-
-  const spec = input.spec;
-  const pruned = prune(
-    spec.root,
-    input.availablePaneIds,
-    { missing, tabs, floats, notes, keepMissing },
-  );
-
-  if (pruned === null) {
-    return {
-      binaryRoot: null,
-      missing,
-      tabs,
-      floats,
-      notes,
-    };
-  }
-
-  // Re-wrap into a LayoutSpec shell so we can reuse the existing
-  // spec→binary lowerer; the pruner returned a tree that contains only
-  // leaf + split nodes (tabs/float already extracted), so this is safe.
-  const dummySpec: LayoutSpec = {
-    version: spec.version,
-    windowId: spec.windowId,
-    createdAt: spec.createdAt,
-    ...(spec.label !== undefined ? { label: spec.label } : {}),
-    root: pruned,
-  };
-  let binaryRoot: BinaryLayoutNode;
-  try {
-    binaryRoot = toBinaryTree(dummySpec);
-  } catch (err) {
-    if (err instanceof LayoutSpecValidationError) {
-      notes.push(`lowering failed: ${err.message}`);
-      return { binaryRoot: null, missing, tabs, floats, notes };
-    }
-    throw err;
-  }
-
-  return {
-    binaryRoot,
-    missing,
-    tabs,
-    floats,
-    notes,
-  };
-}
-
-/** Convenience wrapper that mirrors the save-path ergonomics.
- *  Equivalent to `fromBinaryTree({windowId, root: currentTree, label, createdAt})`
- *  but lives alongside the restore entry so callers find both
- *  directions in one module. */
-export function snapshotWindow(opts: {
-  readonly windowId: string;
-  readonly root: BinaryLayoutNode;
-  readonly label?: string;
-  readonly createdAt?: number;
-}): LayoutSpec {
-  return fromBinaryTree(opts);
-}
-
-// ── Internals ──────────────────────────────────────────────────
-
-interface PruneCtx {
-  missing: PaneRef[];
-  tabs: TabsPlanEntry[];
-  floats: FloatPlanEntry[];
-  notes: string[];
-  keepMissing: boolean;
-}
-
-/** Walk the spec tree and produce a leaner version containing only
- *  leaf + split nodes. Missing leaves either get retained (placeholder
- *  mode) or are removed — split nodes with fewer than 2 surviving
- *  children collapse or vanish. Tabs/float nodes are siphoned off. */
-function prune(
-  node: LayoutSpecNode,
-  available: ReadonlySet<string>,
-  ctx: PruneCtx,
-): LayoutSpecNode | null {
-  if (node.kind === 'leaf') {
-    if (available.has(node.paneRef.paneId)) return node;
-    ctx.missing.push(node.paneRef);
-    if (ctx.keepMissing) return node;
-    ctx.notes.push(`dropped missing leaf ${node.paneRef.paneId}`);
-    return null;
-  }
-  if (node.kind === 'tabs') {
-    const present: PaneRef[] = [];
-    const missing: PaneRef[] = [];
-    for (const p of node.panes) {
-      if (available.has(p.paneId)) present.push(p);
-      else missing.push(p);
-    }
-    ctx.missing.push(...missing);
-    if (present.length > 0) {
-      const active = Math.min(node.active, present.length - 1);
-      ctx.tabs.push({ panes: present, active });
-    } else {
-      ctx.notes.push('tabs container with no available panes');
-    }
-    return null; // tabs don't lower to binary tree
-  }
-  if (node.kind === 'float') {
-    if (available.has(node.pane.paneId)) {
-      ctx.floats.push({ pane: node.pane, rect: node.rect });
-    } else {
-      ctx.missing.push(node.pane);
-      ctx.notes.push(`dropped missing float pane ${node.pane.paneId}`);
-    }
-    return null;
-  }
-  // Split — recurse
-  const survivingChildren: LayoutSpecNode[] = [];
-  const survivingSizes: number[] = [];
-  for (let i = 0; i < node.children.length; i++) {
-    const pruned = prune(node.children[i]!, available, ctx);
-    if (pruned !== null) {
-      survivingChildren.push(pruned);
-      survivingSizes.push(node.sizes[i]!);
-    }
-  }
-  if (survivingChildren.length === 0) return null;
-  if (survivingChildren.length === 1) return survivingChildren[0]!;
-  // Re-normalize sizes so they sum to 1 again.
-  const sum = survivingSizes.reduce((a, b) => a + b, 0);
-  const normalized = survivingSizes.map((s) => s / sum);
-  return {
-    kind: 'split',
-    axis: node.axis,
-    children: survivingChildren,
-    sizes: normalized,
-  };
-}