dsh-hashline-edit 0.2.2 → 0.3.0

package/src/integrations/pi-lens/config.ts

@@ -1,148 +0,0 @@
-/**
- * pi-lens bridge configuration — the on-disk `lens.bridge` setting and its precedence ladder.
- *
- * WHY a seam: the mode is read on every served-row notification and written only by the
- * `/pi-better-edit` command, so both sides must agree on one ladder — env, then project file,
- * then global file, then the `auto` default. A malformed config is never an error: it degrades
- * to "not configured" so a hand-edited file can never break editing.
- *
- * Shape of the shared config file (`CONFIG_REL`, owned by `src/json-config.ts`):
- * `{ "$schema": <LENS_SCHEMA_ID>, "lens": { "bridge": "auto" | "on" | "off" } }`
- * (documented by `schemas/pi-better-edit.json`). Unknown keys are preserved on write.
- *
- * The FILE, the scopes, the read and the preserving atomic write belong to
- * `src/json-config.ts`, which the store settings use too: one ladder, not one per settings owner.
- * This module owns only the `lens.*` keys.
- */
-import { DomainError } from "../../domain-errors.js";
-import {
-  CONFIG_REL,
-  CONFIG_SCHEMA_ID,
-  configFilePath,
-  isRecord,
-  isConfigScope,
-  readScopeConfig,
-  updateConfigFile,
-  type ConfigScope,
-  type ConfigRung,
-} from "../../json-config.js";
-
-export type LensBridgeMode = "auto" | "on" | "off";
-/** The ladder's scopes ARE the config seam's scopes — one enumeration under two names. */
-export type LensBridgeScope = ConfigScope;
-
-/** Environment override; wins over both files. Values outside the enum are ignored, not fatal. */
-export const LENS_BRIDGE_ENV_VAR = "PI_BETTER_EDIT_LENS_BRIDGE";
-
-/** Config location relative to the project root or to the home directory. */
-export const LENS_CONFIG_REL = CONFIG_REL;
-
-/** Published schema id written into config files (see `schemas/pi-better-edit.json`). */
-export const LENS_SCHEMA_ID = CONFIG_SCHEMA_ID;
-
-const LENS_BRIDGE_MODES: readonly LensBridgeMode[] = ["auto", "on", "off"];
-
-/** Runtime guard for values arriving from files, env vars and command arguments. */
-export function isLensBridgeMode(value: unknown): value is LensBridgeMode {
-  return typeof value === "string" && LENS_BRIDGE_MODES.some((mode) => mode === value);
-}
-
-/** Runtime guard for the two config scopes. */
-export function isLensBridgeScope(value: unknown): value is LensBridgeScope {
-  return isConfigScope(value);
-}
-
-function readScopeMode(scope: LensBridgeScope, cwd: string): LensBridgeMode | undefined {
-  const config = readScopeConfig(scope, cwd);
-  if (config === undefined) return undefined;
-  const lens = config.lens;
-  if (!isRecord(lens)) return undefined;
-  return isLensBridgeMode(lens.bridge) ? lens.bridge : undefined;
-}
-
-/**
- * Both scopes' configured modes. Pure read: never creates the directory or the file, never
- * throws. A scope is absent (rather than `undefined`-valued) when its file is missing or holds a
- * value outside the enum.
- */
-export function readLensBridgeConfig(cwd: string): {
-  project?: LensBridgeMode;
-  global?: LensBridgeMode;
-} {
-  const project = readScopeMode("project", cwd);
-  const global = readScopeMode("global", cwd);
-  return {
-    ...(project !== undefined ? { project } : {}),
-    ...(global !== undefined ? { global } : {}),
-  };
-}
-
-function readEnvMode(): LensBridgeMode | undefined {
-  const raw = process.env[LENS_BRIDGE_ENV_VAR];
-  if (raw === undefined) return undefined;
-  const normalized = raw.trim().toLowerCase();
-  return isLensBridgeMode(normalized) ? normalized : undefined;
-}
-
-/**
- * The effective mode and the rung that supplied it. `default` is the built-in `"auto"`, which is a
- * value of the ladder rather than a rung of the file.
- */
-export interface EffectiveLensBridgeMode {
-  readonly mode: LensBridgeMode;
-  readonly source: ConfigRung;
-}
-
-/**
- * Effective mode WITH its rung: env override, then project, then global, then `"auto"`. Never throws.
- * This is the ladder itself, and `resolveEffectiveLensMode` is its value half, so the two cannot
- * disagree about which rung won — a caller that has to NAME the winner (the `/pi-better-edit` status
- * text does) reads it here instead of re-walking the two files.
- */
-export function resolveEffectiveLensModeWithSource(cwd: string): EffectiveLensBridgeMode {
-  const fromEnv = readEnvMode();
-  if (fromEnv !== undefined) return { mode: fromEnv, source: "env" };
-  const config = readLensBridgeConfig(cwd);
-  if (config.project !== undefined) return { mode: config.project, source: "project" };
-  if (config.global !== undefined) return { mode: config.global, source: "global" };
-  return { mode: "auto", source: "default" };
-}
-
-/** Effective mode: env override, then project, then global, then `"auto"`. Never throws. */
-export function resolveEffectiveLensMode(cwd: string): LensBridgeMode {
-  return resolveEffectiveLensModeWithSource(cwd).mode;
-}
-
-/**
- * Persist `mode` for `scope`, preserving unknown top-level keys and other `lens.*` keys already
- * in the file. Creates the directory as needed and replaces the file atomically (sibling temp
- * file + rename, same filesystem). Throws `E_INTERNAL_INVARIANT` — and writes nothing — for a
- * mode or scope outside the enum, which no caller can reach: the command and the overlay narrow
- * both to the enum.
- */
-export function saveLensBridgeConfig(
-  mode: LensBridgeMode,
-  scope: LensBridgeScope,
-  cwd: string,
-): { path: string } {
-  if (!isLensBridgeMode(mode)) {
-    throw new DomainError("E_INTERNAL_INVARIANT", {
-      message: `Unknown lens bridge mode "${String(mode)}".`,
-    });
-  }
-  if (!isLensBridgeScope(scope)) {
-    throw new DomainError("E_INTERNAL_INVARIANT", {
-      message: `Unknown lens bridge scope "${String(scope)}".`,
-    });
-  }
-
-  const path = configFilePath(scope, cwd);
-  // WHY: only `lens.bridge` is ours to set — an existing `$schema` is a deliberate editor-time
-  // WHY: choice and unknown top-level or `lens.*` keys belong to the user, so all of them survive.
-  updateConfigFile(path, (existing) => ({
-    ...existing,
-    lens: { ...(isRecord(existing.lens) ? existing.lens : {}), bridge: mode },
-  }));
-
-  return { path };
-}

package/src/integrations/pi-lens/io-bridge-adapter.ts

@@ -1,234 +0,0 @@
-/**
- * Unified I/O bridge adapter — the only place that records to pi-lens v2.
- *
- * WHY one module for both seams: a v2 `record` entry carries at most one facet
- * of each kind, and the two domain-neutral seams (`src/served-spans.ts`,
- * `src/mutated-files.ts`) already separate reads from mutations, so each
- * notification maps to single-facet `record` calls. Edit-plus-preview pairs
- * therefore travel as two back-to-back calls in producer order, never as one
- * atomic compound.
- *
- * Read evidence: a notification that carries verbatim `content` is recorded span
- * by span, each span in its own single-range call with its slice (`content` is
- * valid only for a single contiguous range, and slicing keeps multi-span
- * notifications honest). A span whose slice fails is dropped, never sent short.
- * A notification without `content` — diff previews and reject-and-serve rows,
- * where no raw text is at hand — is recorded as ONE call carrying every range
- * with `evidence: "disk"`, the v1-equivalent behavior. `lineHashes` are never
- * sent: they would need the bridge's hash algorithm, while `content` lets the
- * bridge hash in memory with its own.
- *
- * Silence is the contract: these observers run inside core tool execution, so
- * nothing here logs and nothing throws — a broken bridge degrades to "no I/O
- * mirrored", never to a failed read, edit or write. Drops are counted instead,
- * for tests only. An explicit `off` mode is a configuration choice, not a failed
- * mirror, so it is never a drop.
- */
-import { isAbsolute } from "node:path";
-import { addMutatedFileObserver, type MutatedFileNotification } from "../../mutated-files.js";
-import { addServedSpanObserver, type ServedSpanNotification } from "../../served-spans.js";
-import { resolveEffectiveLensMode } from "./config.js";
-import {
-  getIOBridge,
-  IO_BRIDGE_CONSUMER,
-  sliceSpanContent,
-  type IOBridge,
-  type IOBridgeMutate,
-  type IOBridgeRange,
-} from "./io-bridge.js";
-
-let dropCount = 0;
-
-/** Test helper: how many mirrors this adapter dropped since the last reset. */
-export function getIODropCountForTests(): number {
-  return dropCount;
-}
-
-/** Test helper: reset the drop tally so counts cannot leak between tests. */
-export function resetIODropCountForTests(): void {
-  dropCount = 0;
-}
-
-/**
- * SAFETY: pi-lens rejects a malformed range outright (`isValidRange`), so a span
- * that cannot be expressed as one is dropped here rather than sent as a guess.
- * The seams guarantee valid spans; this guard is defense in depth.
- */
-function toBridgeRange(startLine: number, lineCount: number): IOBridgeRange | undefined {
-  if (!Number.isInteger(startLine) || !Number.isInteger(lineCount)) return undefined;
-  if (startLine < 1 || lineCount < 1) return undefined;
-  return [startLine, startLine + lineCount - 1];
-}
-
-/**
- * Map one mutation notification to its facet, or `undefined` when it cannot be
- * expressed truthfully. An empty range list means the whole file changed, which
- * v2 names `write`: `edit` requires a non-empty `ranges`.
- */
-function toMutateFacet(notification: MutatedFileNotification): IOBridgeMutate | undefined {
-  if (!isAbsolute(notification.filePath)) return undefined;
-  if (notification.kind === "write" || notification.ranges.length === 0) {
-    return { kind: "write" };
-  }
-  const ranges: IOBridgeRange[] = [];
-  for (const span of notification.ranges) {
-    const range = toBridgeRange(span.startLine, span.lineCount);
-    if (range === undefined) return undefined;
-    ranges.push(range);
-  }
-  return { kind: "edit", ranges };
-}
-
-/** Record one mutation notification; every failure path counts one drop. */
-function recordMutated(bridge: IOBridge, notification: MutatedFileNotification): void {
-  const mutate = toMutateFacet(notification);
-  if (mutate === undefined) {
-    dropCount += 1;
-    return;
-  }
-  try {
-    const result = bridge.record({
-      filePath: notification.filePath,
-      consumer: IO_BRIDGE_CONSUMER,
-      mutate,
-    });
-    if (result?.mutate?.accepted !== true) dropCount += 1;
-  } catch {
-    // SAFETY: advisory-only — a refused record must not propagate into the edit
-    // SAFETY: or write that already landed, and the failure is the bridge's to
-    // SAFETY: report.
-    dropCount += 1;
-  }
-}
-
-/** Record the caller slice of one single-range span; a failed slice counts a drop. */
-function recordSlicedSpan(
-  bridge: IOBridge,
-  filePath: string,
-  startLine: number,
-  lineCount: number,
-  content: string,
-): void {
-  const range = toBridgeRange(startLine, lineCount);
-  const slice = range === undefined ? undefined : sliceSpanContent(content, startLine, lineCount);
-  if (range === undefined || slice === undefined) {
-    dropCount += 1;
-    return;
-  }
-  try {
-    const result = bridge.record({
-      filePath,
-      consumer: IO_BRIDGE_CONSUMER,
-      read: { ranges: [range], content: slice },
-    });
-    if (result?.read?.accepted !== true) dropCount += 1;
-  } catch {
-    // SAFETY: advisory-only — one rejected span must not stop the remaining
-    // SAFETY: spans of the same notification, and the failure is the bridge's
-    // SAFETY: to report.
-    dropCount += 1;
-  }
-}
-
-/** Record every span of a text-less notification as ONE disk-evidence call. */
-function recordDiskReads(
-  bridge: IOBridge,
-  filePath: string,
-  notification: ServedSpanNotification,
-): void {
-  const ranges: IOBridgeRange[] = [];
-  for (const span of notification.spans) {
-    const range = toBridgeRange(span.startLine, span.lineCount);
-    if (range === undefined) {
-      dropCount += 1;
-      return;
-    }
-    ranges.push(range);
-  }
-  try {
-    const result = bridge.record({
-      filePath,
-      consumer: IO_BRIDGE_CONSUMER,
-      read: { ranges, evidence: "disk" },
-    });
-    if (result?.read?.accepted !== true) dropCount += 1;
-  } catch {
-    // SAFETY: advisory-only — the bridge's failure belongs to the bridge, never
-    // SAFETY: to the read or edit that served the rows.
-    dropCount += 1;
-  }
-}
-
-/** Record one served-span notification: caller slices when present, else one disk batch. */
-function recordServedSpans(bridge: IOBridge, notification: ServedSpanNotification): void {
-  const content = notification.content;
-  if (typeof content !== "string") {
-    recordDiskReads(bridge, notification.filePath, notification);
-    return;
-  }
-  for (const span of notification.spans) {
-    recordSlicedSpan(bridge, notification.filePath, span.startLine, span.lineCount, content);
-  }
-}
-
-/**
- * Subscribe both mirrors and return the combined unsubscribe function.
- *
- * `getCwd` is injectable because the observer path has no command context:
- * `process.cwd()` stands in for the session cwd (pi launches in it), while the
- * `/pi-better-edit` command resolves the exact `ctx.cwd`. The mode is re-read per
- * notification, so a mode change takes effect immediately.
- */
-export function attachIOBridgeAdapter(options?: { getCwd?: () => string }): () => void {
-  const getCwd = options?.getCwd ?? ((): string => process.cwd());
-  const resolveMode = (): string | undefined => {
-    try {
-      return resolveEffectiveLensMode(getCwd());
-    } catch {
-      // SAFETY: an unusable cwd means the mode cannot be resolved, so nothing
-      // SAFETY: is mirrored and no drop is counted for a config read.
-      return undefined;
-    }
-  };
-  const detachMutated = addMutatedFileObserver((notification: MutatedFileNotification): void => {
-    try {
-      const mode = resolveMode();
-      if (mode === undefined || mode === "off") return;
-      // WHY: `auto` treats an absent bridge as disabled and `on` cannot conjure
-      // WHY: one, so both modes share this single no-op path — the mode gate
-      // WHY: above is the only difference between them, and an absent bridge is
-      // WHY: still a dropped mirror.
-      const bridge = getIOBridge();
-      if (bridge === undefined) {
-        dropCount += 1;
-        return;
-      }
-      recordMutated(bridge, notification);
-    } catch {
-      // SAFETY: advisory-only — this runs inside core tool execution, so no
-      // SAFETY: failure may propagate into the edit or write that produced the
-      // SAFETY: mutation.
-    }
-  });
-  const detachServed = addServedSpanObserver((notification: ServedSpanNotification): void => {
-    try {
-      if (notification.spans.length === 0 || !isAbsolute(notification.filePath)) return;
-      const mode = resolveMode();
-      if (mode === undefined || mode === "off") return;
-      const bridge = getIOBridge();
-      if (bridge === undefined) {
-        dropCount += 1;
-        return;
-      }
-      recordServedSpans(bridge, notification);
-    } catch {
-      // SAFETY: advisory-only — this runs inside core tool execution, so no
-      // SAFETY: failure may propagate into the read or edit that served the
-      // SAFETY: rows.
-    }
-  });
-  return () => {
-    detachMutated();
-    detachServed();
-  };
-}

package/src/integrations/pi-lens/io-bridge.ts

@@ -1,112 +0,0 @@
-/**
- * Unified pi-lens File I/O Lifecycle Bridge v2 — the only place that knows the
- * `pi-lens:io-bridge` mount exists.
- *
- * WHY a separate module: the observer seams (`src/served-spans.ts`,
- * `src/mutated-files.ts`) are domain-neutral and must not reference any
- * extension, while this module is the integration edge that turns served and
- * mutated notifications into `record` calls. Detection is structural (a global
- * symbol key plus a version and shape check), so nothing here imports pi-lens.
- * When the bridge is absent, or the mode is `off`, every notification is a
- * no-op.
- *
- * The structural copies below are the v2-native subset this integration sends —
- * no `v1-compat` fields, which exist only for the frozen v1 shims. The pi-lens
- * contract file (`clients/io-bridge-contract.ts`) is authoritative when this
- * module and the migration guide disagree.
- *
- * Silence is the contract: the observers run inside core tool execution, so
- * nothing here logs and nothing throws — a broken bridge degrades to "no I/O
- * mirrored", never to a failed read, edit or write.
- */
-
-/** Stable symbol key — identical across module reloads in one process. */
-const IO_BRIDGE_KEY = "pi-lens:io-bridge";
-
-/** Bridge API version this integration speaks. A mismatch means unsupported. */
-export const IO_BRIDGE_VERSION = 2;
-
-/** Caller identity for logging and telemetry on the pi-lens side. */
-export const IO_BRIDGE_CONSUMER = "pi-better-edit";
-
-/** One 1-indexed closed line interval: `[start, end]` with `end >= start`. */
-export type IOBridgeRange = [start: number, end: number];
-
-/** Read facet this integration sends: caller evidence, never `disk` by default. */
-interface IOBridgeRead {
-  ranges: IOBridgeRange[];
-  content?: string;
-  evidence?: "caller" | "disk";
-}
-
-/** Mutation facet this integration sends. `delete` has no producer here. */
-export type IOBridgeMutate = { kind: "edit"; ranges: IOBridgeRange[] } | { kind: "write" };
-
-/** One `record` entry: at most one facet of each kind. */
-interface IOBridgeEntry {
-  filePath: string;
-  consumer?: string;
-  mutate?: IOBridgeMutate;
-  read?: IOBridgeRead;
-}
-
-/** One facet outcome. `record` never throws; refusals arrive as outcomes. */
-type IOBridgeOutcome = { accepted: true } | { accepted: false; reason: string };
-
-/** Per-facet outcomes of one `record` call. */
-interface IOBridgeResult {
-  read?: IOBridgeOutcome;
-  mutate?: IOBridgeOutcome;
-}
-
-/** Structural view of the bridge published by pi-lens; only `record` is read. */
-export interface IOBridge {
-  readonly version: number;
-  record(entry: IOBridgeEntry): IOBridgeResult;
-}
-
-/**
- * SAFETY: resolved per call rather than captured at module load, so a bridge
- * mounted after the adapter is attached is still found, and a bridge swapped
- * by another extension is honoured. A version mismatch means "unsupported",
- * never "reset": the caller simply records nothing.
- */
-export function getIOBridge(): IOBridge | undefined {
-  // SAFETY: `globalThis` carries no symbol index signature in the TS lib, so
-  // SAFETY: one cast is what makes the symbol-keyed lookup expressible at all;
-  // SAFETY: the value stays `unknown`, so the version and method checks below
-  // SAFETY: are what prove the shape, and the I/O bridge is the only thing
-  // SAFETY: published under this key.
-  const maybe = (globalThis as unknown as Record<symbol, unknown>)[Symbol.for(IO_BRIDGE_KEY)];
-  if (typeof maybe !== "object" || maybe === null) return undefined;
-  const bridge = maybe as Partial<IOBridge>;
-  if (bridge.version !== IO_BRIDGE_VERSION || typeof bridge.record !== "function") {
-    return undefined;
-  }
-  return bridge as IOBridge;
-}
-
-/**
- * Slice the verbatim span lines out of raw file text.
- *
- * WHY a slice, not the whole text: `content` is span-relative and valid only for
- * a single contiguous range, so each span of a multi-span notification travels
- * in its own single-range `record` call. The split is CRLF-tolerant (`/\r?\n/`),
- * and the terminal newline's empty entry is a sentinel rather than a line, so the
- * returned text splits back into exactly the span's lines when the bridge hashes
- * it. Returns `undefined` when the text is shorter than the span claims — the
- * caller then drops the span rather than sending a short slice as the whole span.
- */
-export function sliceSpanContent(
-  content: string,
-  startLine: number,
-  lineCount: number,
-): string | undefined {
-  if (!Number.isInteger(startLine) || !Number.isInteger(lineCount)) return undefined;
-  const start = startLine - 1;
-  if (start < 0 || lineCount < 1) return undefined;
-  const lines = content.split(/\r?\n/);
-  if (content.endsWith("\n")) lines.pop();
-  if (start + lineCount > lines.length) return undefined;
-  return lines.slice(start, start + lineCount).join("\n");
-}