chainlesschain 0.165.6 → 0.165.8

package/src/lib/session-workbench-store.js

@@ -0,0 +1,466 @@
+/**
+ * Durable, CLI-owned Sessions Workbench grouping authority.
+ *
+ * IDE windows only render this state through `cc session projection`. Every
+ * mutation is an exact revision CAS under the shared cross-process file lock,
+ * so two IDE windows cannot silently overwrite each other's group changes.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  mutateSecurityStore,
+  readSecurityStore,
+} from "./durable-security-store.js";
+import { projectionRevision } from "./session-projection.js";
+import {
+  ensureTrustedSessionLifecycleScope,
+  resolveTrustedSessionLifecycleScope,
+} from "./session-lifecycle-scope.js";
+
+export const SESSION_WORKBENCH_STATE_SCHEMA =
+  "chainlesschain.session-workbench-state/v1";
+export const MAX_SESSION_GROUPS = 128;
+export const MAX_SESSION_GROUP_NAME_CHARS = 80;
+export const MAX_SESSION_GROUP_MEMBERSHIPS = 4096;
+
+export function defaultSessionWorkbenchStatePath(options = {}) {
+  return resolveTrustedSessionLifecycleScope(options).workbenchStatePath;
+}
+
+function stateError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function cleanText(value, label, maxChars) {
+  const text = String(value ?? "").trim();
+  if (!text || text.length > maxChars || /[\u0000-\u001f\u007f]/u.test(text)) {
+    throw stateError(
+      "SESSION_GROUP_INVALID_ARGUMENT",
+      `${label} must be 1-${maxChars} characters without control characters`,
+    );
+  }
+  return text;
+}
+
+function cleanGroupId(value) {
+  const id = cleanText(value, "group id", 128);
+  if (!/^group-[a-zA-Z0-9_-]+$/u.test(id)) {
+    throw stateError(
+      "SESSION_GROUP_INVALID_ARGUMENT",
+      "group id has an unsupported format",
+    );
+  }
+  return id;
+}
+
+function cleanSessionId(value) {
+  const id = cleanText(value, "canonical session id", 512);
+  if (!/^[a-z_]+:[^\s]+$/u.test(id)) {
+    throw stateError(
+      "SESSION_GROUP_INVALID_ARGUMENT",
+      "session id must be a canonical kind-prefixed projection id",
+    );
+  }
+  return id;
+}
+
+function emptyState() {
+  return {
+    schema: SESSION_WORKBENCH_STATE_SCHEMA,
+    generation: 0,
+    groups: [],
+    memberships: {},
+  };
+}
+
+function groupSort(left, right) {
+  return (
+    left.order - right.order ||
+    left.name.localeCompare(right.name) ||
+    left.id.localeCompare(right.id)
+  );
+}
+
+function normalizeState(raw) {
+  if (
+    raw &&
+    typeof raw === "object" &&
+    !Array.isArray(raw) &&
+    Object.keys(raw).length === 0
+  ) {
+    return emptyState();
+  }
+  if (
+    !raw ||
+    typeof raw !== "object" ||
+    Array.isArray(raw) ||
+    raw.schema !== SESSION_WORKBENCH_STATE_SCHEMA ||
+    !Number.isSafeInteger(raw.generation) ||
+    raw.generation < 0 ||
+    !Array.isArray(raw.groups) ||
+    !raw.memberships ||
+    typeof raw.memberships !== "object" ||
+    Array.isArray(raw.memberships)
+  ) {
+    throw stateError(
+      "SESSION_GROUP_STORE_CORRUPT",
+      "session workbench state is malformed",
+    );
+  }
+  if (raw.groups.length > MAX_SESSION_GROUPS) {
+    throw stateError(
+      "SESSION_GROUP_STORE_CORRUPT",
+      "session workbench state exceeds the group limit",
+    );
+  }
+  const ids = new Set();
+  const names = new Set();
+  const groups = raw.groups.map((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw stateError(
+        "SESSION_GROUP_STORE_CORRUPT",
+        "session group entry is malformed",
+      );
+    }
+    const id = cleanGroupId(entry.id);
+    const name = cleanText(
+      entry.name,
+      "group name",
+      MAX_SESSION_GROUP_NAME_CHARS,
+    );
+    const order = Number(entry.order);
+    if (!Number.isSafeInteger(order) || order < 0 || order > 100_000) {
+      throw stateError(
+        "SESSION_GROUP_STORE_CORRUPT",
+        "session group order is malformed",
+      );
+    }
+    if (ids.has(id) || names.has(name.toLowerCase())) {
+      throw stateError(
+        "SESSION_GROUP_STORE_CORRUPT",
+        "session group ids and names must be unique",
+      );
+    }
+    ids.add(id);
+    names.add(name.toLowerCase());
+    return { id, name, order };
+  });
+  const membershipEntries = Object.entries(raw.memberships);
+  if (membershipEntries.length > MAX_SESSION_GROUP_MEMBERSHIPS) {
+    throw stateError(
+      "SESSION_GROUP_STORE_CORRUPT",
+      "session workbench state exceeds the membership limit",
+    );
+  }
+  const memberships = {};
+  for (const [rawSessionId, rawGroupId] of membershipEntries) {
+    const sessionId = cleanSessionId(rawSessionId);
+    const groupId = cleanGroupId(rawGroupId);
+    if (!ids.has(groupId)) {
+      throw stateError(
+        "SESSION_GROUP_STORE_CORRUPT",
+        `session membership references missing group ${groupId}`,
+      );
+    }
+    memberships[sessionId] = groupId;
+  }
+  return {
+    schema: SESSION_WORKBENCH_STATE_SCHEMA,
+    generation: raw.generation,
+    groups: groups.sort(groupSort),
+    memberships: Object.fromEntries(
+      Object.entries(memberships).sort(([left], [right]) =>
+        left.localeCompare(right),
+      ),
+    ),
+  };
+}
+
+function revisionFor(state) {
+  return projectionRevision({
+    schema: state.schema,
+    generation: state.generation,
+    groups: state.groups,
+    memberships: state.memberships,
+  });
+}
+
+function publicProjection(state) {
+  const normalized = normalizeState(state);
+  return {
+    authority: "cli",
+    connected: true,
+    revision: revisionFor(normalized),
+    generation: normalized.generation,
+    items: normalized.groups.map((group) => ({ ...group })),
+    assignments: Object.entries(normalized.memberships).map(
+      ([sessionId, groupId]) => ({ sessionId, groupId }),
+    ),
+  };
+}
+
+function requireRevision(state, expectedRevision) {
+  const currentRevision = revisionFor(state);
+  if (
+    typeof expectedRevision !== "string" ||
+    !expectedRevision ||
+    expectedRevision !== currentRevision
+  ) {
+    throw stateError(
+      "SESSION_GROUP_STALE",
+      "session group revision changed; refresh before retrying",
+      { expectedRevision: expectedRevision || null, currentRevision },
+    );
+  }
+}
+
+function reindex(groups) {
+  return [...groups]
+    .sort(groupSort)
+    .map((group, order) => ({ ...group, order }));
+}
+
+export class SessionWorkbenchStore {
+  constructor(options = {}) {
+    const {
+      filePath: configuredFilePath,
+      launchEnv,
+      cwd,
+      uuid = randomUUID,
+      lockOptions,
+    } = options;
+    const usesDefaultFilePath = configuredFilePath === undefined;
+    this._lifecycleScope = usesDefaultFilePath
+      ? resolveTrustedSessionLifecycleScope({ launchEnv, cwd })
+      : null;
+    this.filePath = usesDefaultFilePath
+      ? this._lifecycleScope.workbenchStatePath
+      : configuredFilePath;
+    this.uuid = uuid;
+    this.lockOptions = lockOptions;
+  }
+
+  _prepareStorage() {
+    if (this._lifecycleScope?.kind === "project") {
+      ensureTrustedSessionLifecycleScope(this._lifecycleScope);
+    }
+  }
+
+  projection() {
+    this._prepareStorage();
+    return publicProjection(
+      normalizeState(readSecurityStore(this.filePath, "session workbench")),
+    );
+  }
+
+  _mutate(expectedRevision, mutator) {
+    this._prepareStorage();
+    return mutateSecurityStore(
+      this.filePath,
+      "session workbench",
+      (draft) => {
+        const current = normalizeState(draft);
+        requireRevision(current, expectedRevision);
+        const next = normalizeState(mutator(structuredClone(current)));
+        next.generation = current.generation + 1;
+        for (const key of Object.keys(draft)) delete draft[key];
+        Object.assign(draft, next);
+        return publicProjection(next);
+      },
+      this.lockOptions,
+    );
+  }
+
+  createGroup({ name, order = null, expectedRevision } = {}) {
+    const normalizedName = cleanText(
+      name,
+      "group name",
+      MAX_SESSION_GROUP_NAME_CHARS,
+    );
+    return this._mutate(expectedRevision, (state) => {
+      if (state.groups.length >= MAX_SESSION_GROUPS) {
+        throw stateError(
+          "SESSION_GROUP_LIMIT",
+          `session groups are limited to ${MAX_SESSION_GROUPS}`,
+        );
+      }
+      if (
+        state.groups.some(
+          (group) => group.name.toLowerCase() === normalizedName.toLowerCase(),
+        )
+      ) {
+        throw stateError(
+          "SESSION_GROUP_CONFLICT",
+          "session group name already exists",
+        );
+      }
+      const requestedOrder =
+        order == null ? state.groups.length : Number(order);
+      if (
+        !Number.isSafeInteger(requestedOrder) ||
+        requestedOrder < 0 ||
+        requestedOrder > state.groups.length
+      ) {
+        throw stateError(
+          "SESSION_GROUP_INVALID_ARGUMENT",
+          "group order must be within the current group list",
+        );
+      }
+      state.groups = state.groups.map((group) =>
+        group.order >= requestedOrder
+          ? { ...group, order: group.order + 1 }
+          : group,
+      );
+      state.groups.push({
+        id: `group-${this.uuid().replaceAll("-", "")}`,
+        name: normalizedName,
+        order: requestedOrder,
+      });
+      state.groups = reindex(state.groups);
+      return state;
+    });
+  }
+
+  renameGroup({ groupId, name, expectedRevision } = {}) {
+    const id = cleanGroupId(groupId);
+    const normalizedName = cleanText(
+      name,
+      "group name",
+      MAX_SESSION_GROUP_NAME_CHARS,
+    );
+    return this._mutate(expectedRevision, (state) => {
+      const group = state.groups.find((entry) => entry.id === id);
+      if (!group) {
+        throw stateError(
+          "SESSION_GROUP_NOT_FOUND",
+          `session group ${id} not found`,
+        );
+      }
+      if (
+        state.groups.some(
+          (entry) =>
+            entry.id !== id &&
+            entry.name.toLowerCase() === normalizedName.toLowerCase(),
+        )
+      ) {
+        throw stateError(
+          "SESSION_GROUP_CONFLICT",
+          "session group name already exists",
+        );
+      }
+      group.name = normalizedName;
+      return state;
+    });
+  }
+
+  deleteGroup({ groupId, expectedRevision } = {}) {
+    const id = cleanGroupId(groupId);
+    return this._mutate(expectedRevision, (state) => {
+      if (!state.groups.some((entry) => entry.id === id)) {
+        throw stateError(
+          "SESSION_GROUP_NOT_FOUND",
+          `session group ${id} not found`,
+        );
+      }
+      state.groups = reindex(state.groups.filter((entry) => entry.id !== id));
+      state.memberships = Object.fromEntries(
+        Object.entries(state.memberships).filter(
+          ([, groupId]) => groupId !== id,
+        ),
+      );
+      return state;
+    });
+  }
+
+  setGroupOrder({ groupId, order, expectedRevision } = {}) {
+    const id = cleanGroupId(groupId);
+    const requestedOrder = Number(order);
+    return this._mutate(expectedRevision, (state) => {
+      const current = state.groups.find((entry) => entry.id === id);
+      if (!current) {
+        throw stateError(
+          "SESSION_GROUP_NOT_FOUND",
+          `session group ${id} not found`,
+        );
+      }
+      if (
+        !Number.isSafeInteger(requestedOrder) ||
+        requestedOrder < 0 ||
+        requestedOrder >= state.groups.length
+      ) {
+        throw stateError(
+          "SESSION_GROUP_INVALID_ARGUMENT",
+          "group order must identify an existing position",
+        );
+      }
+      const without = state.groups.filter((entry) => entry.id !== id);
+      without.splice(requestedOrder, 0, current);
+      state.groups = without.map((entry, index) => ({
+        ...entry,
+        order: index,
+      }));
+      return state;
+    });
+  }
+
+  moveSessions({ groupId = null, sessionIds, expectedRevision } = {}) {
+    const target =
+      groupId == null || groupId === "" || groupId === "ungrouped"
+        ? null
+        : cleanGroupId(groupId);
+    if (!Array.isArray(sessionIds) || sessionIds.length === 0) {
+      throw stateError(
+        "SESSION_GROUP_INVALID_ARGUMENT",
+        "at least one canonical session id is required",
+      );
+    }
+    const ids = [...new Set(sessionIds.map(cleanSessionId))];
+    if (ids.length > 256) {
+      throw stateError(
+        "SESSION_GROUP_INVALID_ARGUMENT",
+        "one batch move is limited to 256 sessions",
+      );
+    }
+    return this._mutate(expectedRevision, (state) => {
+      if (target && !state.groups.some((entry) => entry.id === target)) {
+        throw stateError(
+          "SESSION_GROUP_NOT_FOUND",
+          `session group ${target} not found`,
+        );
+      }
+      const nextCount = new Set([
+        ...Object.keys(state.memberships),
+        ...(target ? ids : []),
+      ]).size;
+      if (nextCount > MAX_SESSION_GROUP_MEMBERSHIPS) {
+        throw stateError(
+          "SESSION_GROUP_LIMIT",
+          `session memberships are limited to ${MAX_SESSION_GROUP_MEMBERSHIPS}`,
+        );
+      }
+      for (const sessionId of ids) {
+        if (target) state.memberships[sessionId] = target;
+        else delete state.memberships[sessionId];
+      }
+      return state;
+    });
+  }
+}
+
+export function disconnectedSessionGroups(reasonText) {
+  return {
+    authority: "cli",
+    connected: false,
+    revision: null,
+    generation: 0,
+    reason: String(reasonText || "session group store unavailable").slice(
+      0,
+      240,
+    ),
+    items: [],
+    assignments: [],
+  };
+}

package/src/lib/spellcheck.js

@@ -0,0 +1,211 @@
+/**
+ * Local spellcheck adapter for REPL text.
+ *
+ * No dictionary is bundled and no text leaves the machine: a caller may opt
+ * into an installed aspell, hunspell, or ispell executable. Fenced code is
+ * removed before invocation so identifiers and examples do not become noisy
+ * spelling diagnostics.
+ */
+
+import { executionBroker } from "./process-execution-broker/index.js";
+
+export const SPELLCHECK_ADAPTERS = Object.freeze([
+  Object.freeze({ command: "aspell", args: Object.freeze(["list"]) }),
+  Object.freeze({ command: "hunspell", args: Object.freeze(["list"]) }),
+  Object.freeze({ command: "ispell", args: Object.freeze(["-l"]) }),
+]);
+
+export const MAX_SPELLCHECK_INPUT_BYTES = 1024 * 1024;
+export const MAX_SPELLCHECK_WORDS = 200;
+
+const defaultDeps = Object.freeze({
+  spawnSync(command, args, options) {
+    return executionBroker.spawnSync(command, args, {
+      origin: "spellcheck:local-adapter",
+      scope: "spellcheck",
+      policy: "allow",
+      ...options,
+    });
+  },
+});
+
+/** Parse the REPL's local-only `/spellcheck` command. */
+export function parseSpellcheckCommand(line) {
+  const input = String(line || "").trim();
+  if (input !== "/spellcheck" && !input.startsWith("/spellcheck ")) {
+    return null;
+  }
+  const argument = input.slice("/spellcheck".length).trim();
+  if (!argument || argument === "status")
+    return Object.freeze({ action: "status" });
+  if (argument === "on" || argument === "off") {
+    return Object.freeze({ action: argument });
+  }
+  return Object.freeze({ action: "check", text: argument });
+}
+
+function bool(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return null;
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return null;
+}
+
+function safeCommand(value) {
+  if (
+    typeof value !== "string" ||
+    !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(value)
+  ) {
+    throw new TypeError("spellcheck command is invalid");
+  }
+  return value;
+}
+
+function spawnOptions(input) {
+  return {
+    input,
+    encoding: "utf8",
+    timeout: 2500,
+    maxBuffer: 512 * 1024,
+    shell: false,
+    windowsHide: true,
+  };
+}
+
+/** Resolve the opt-out policy without treating project text as authority. */
+export function resolveSpellcheckEnabled(options = {}) {
+  const explicit = bool(options.enabled);
+  if (explicit !== null) return explicit;
+  const env = options.env || process.env;
+  const environment = bool(env.CC_SPELLCHECK ?? env.CLAUDE_CODE_SPELLCHECK);
+  if (environment !== null) return environment;
+  const configured = bool(
+    options.config?.cli?.spellcheck ?? options.config?.spellcheck,
+  );
+  return configured ?? true;
+}
+
+/** Strip fenced Markdown code while retaining the surrounding prose. */
+export function suppressFencedCodeBlocks(value) {
+  const output = [];
+  let fence = null;
+  for (const line of String(value ?? "")
+    .replace(/\r\n?/g, "\n")
+    .split("\n")) {
+    const marker = line.match(/^\s*(`{3,}|~{3,})/u)?.[1] || null;
+    if (fence === null && marker) {
+      fence = { character: marker[0], length: marker.length };
+      continue;
+    }
+    if (
+      fence !== null &&
+      marker &&
+      marker[0] === fence.character &&
+      marker.length >= fence.length
+    ) {
+      fence = null;
+      continue;
+    }
+    if (fence === null) output.push(line);
+  }
+  return output.join("\n");
+}
+
+function findAdapter(command, deps) {
+  const requested = command == null ? null : safeCommand(command);
+  const candidates = requested
+    ? SPELLCHECK_ADAPTERS.filter((adapter) => adapter.command === requested)
+    : SPELLCHECK_ADAPTERS;
+  if (requested && candidates.length === 0) {
+    return null;
+  }
+  for (const adapter of candidates) {
+    const probe = deps.spawnSync(
+      adapter.command,
+      ["--version"],
+      spawnOptions(""),
+    );
+    if (!probe?.error && probe?.status === 0) return adapter;
+  }
+  return null;
+}
+
+function projectWords(output) {
+  const words = [];
+  const seen = new Set();
+  for (const raw of String(output || "").split(/\r?\n/u)) {
+    const word = raw.trim();
+    if (!word || word.length > 128 || !/^[\p{L}][\p{L}'-]*$/u.test(word))
+      continue;
+    const key = word.toLocaleLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    words.push(word);
+    if (words.length >= MAX_SPELLCHECK_WORDS) break;
+  }
+  return Object.freeze(words);
+}
+
+/**
+ * Check prose with a local executable. Error objects and tool stderr are never
+ * returned because they can expose local paths, dictionary options, or input.
+ */
+export function spellcheckText(value, options = {}) {
+  const enabled = resolveSpellcheckEnabled(options);
+  if (!enabled) {
+    return Object.freeze({
+      enabled: false,
+      available: false,
+      adapter: null,
+      words: Object.freeze([]),
+      reason: "disabled",
+    });
+  }
+  const prose = suppressFencedCodeBlocks(value);
+  if (Buffer.byteLength(prose, "utf8") > MAX_SPELLCHECK_INPUT_BYTES) {
+    throw new RangeError("spellcheck input exceeds the maximum size");
+  }
+  if (!prose.trim()) {
+    return Object.freeze({
+      enabled: true,
+      available: true,
+      adapter: null,
+      words: Object.freeze([]),
+      reason: "empty",
+    });
+  }
+  const deps = { ...defaultDeps, ...(options.deps || {}) };
+  const adapter = findAdapter(options.command, deps);
+  if (!adapter) {
+    return Object.freeze({
+      enabled: true,
+      available: false,
+      adapter: null,
+      words: Object.freeze([]),
+      reason: "unavailable",
+    });
+  }
+  const result = deps.spawnSync(
+    adapter.command,
+    adapter.args,
+    spawnOptions(prose),
+  );
+  if (result?.error || result?.status !== 0) {
+    return Object.freeze({
+      enabled: true,
+      available: false,
+      adapter: adapter.command,
+      words: Object.freeze([]),
+      reason: "failed",
+    });
+  }
+  return Object.freeze({
+    enabled: true,
+    available: true,
+    adapter: adapter.command,
+    words: projectWords(result.stdout),
+    reason: null,
+  });
+}