dsh-agent-team-ui-testing 0.1.1 → 0.1.3

package/core/geometry.js

@@ -0,0 +1,217 @@
+/**
+ * Coordinate-space transforms (P0-C, M0 §3 family C).
+ *
+ * Pure affine 2D transforms between explicit coordinate spaces. Spaces are never assumed to be
+ * interchangeable: a mapping carries `from`, `to` and `geometryVersion`, and comparisons refuse
+ * mismatched spaces or geometry versions. No platform/geometry discovery happens here.
+ */
+import { ERROR_CODES } from './contracts.js';
+import { AdapterError } from './errors.js';
+
+/** Every coordinate space the neutral model may talk about. */
+export const COORDINATE_SPACES = Object.freeze([
+  'document-css-px',
+  'image-px',
+  'viewport-css-px',
+  'screen-logical-px',
+  'screen-physical-px',
+]);
+
+const SPACE_SET = new Set(COORDINATE_SPACES);
+
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function assertSpace(space, field) {
+  if (typeof space !== 'string' || !SPACE_SET.has(space)) {
+    throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, `unknown coordinate space for ${field}`, {
+      details: { field, value: typeof space === 'string' ? space : null },
+    });
+  }
+  return space;
+}
+
+function assertNumber(value, field) {
+  if (!isFiniteNumber(value)) {
+    throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, `${field} must be a finite number`, {
+      details: { field, value: Number.isNaN(value) ? 'NaN' : typeof value },
+    });
+  }
+  return value;
+}
+
+function assertVersion(value) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, 'geometryVersion must be a non-negative integer', {
+      details: { field: 'geometryVersion', value: Number.isFinite(value) ? value : null },
+    });
+  }
+  return value;
+}
+
+function assertPoint(point, field = 'point') {
+  if (point === null || typeof point !== 'object') {
+    throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, `${field} must be an object with x/y`, {
+      details: { field },
+    });
+  }
+  return { x: assertNumber(point.x, `${field}.x`), y: assertNumber(point.y, `${field}.y`) };
+}
+
+function assertRect(rect, field = 'rect') {
+  if (rect === null || typeof rect !== 'object') {
+    throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, `${field} must be an object with x/y/width/height`, {
+      details: { field },
+    });
+  }
+  return {
+    x: assertNumber(rect.x, `${field}.x`),
+    y: assertNumber(rect.y, `${field}.y`),
+    width: assertNumber(rect.width, `${field}.width`),
+    height: assertNumber(rect.height, `${field}.height`),
+  };
+}
+
+/**
+ * @param {{from:string, to:string, scaleX?:number, scaleY?:number, offsetX?:number,
+ *   offsetY?:number, geometryVersion?:number}} input
+ * @returns {{from:string, to:string, scaleX:number, scaleY:number, offsetX:number,
+ *   offsetY:number, geometryVersion:number}}
+ */
+export function createTransform({
+  from,
+  to,
+  scaleX = 1,
+  scaleY = 1,
+  offsetX = 0,
+  offsetY = 0,
+  geometryVersion = 1,
+} = {}) {
+  return {
+    from: assertSpace(from, 'from'),
+    to: assertSpace(to, 'to'),
+    scaleX: assertNumber(scaleX, 'scaleX'),
+    scaleY: assertNumber(scaleY, 'scaleY'),
+    offsetX: assertNumber(offsetX, 'offsetX'),
+    offsetY: assertNumber(offsetY, 'offsetY'),
+    geometryVersion: assertVersion(geometryVersion),
+  };
+}
+
+/** Identity mapping within one space. */
+export function identityTransform(space, geometryVersion = 1) {
+  return createTransform({ from: space, to: space, geometryVersion });
+}
+
+function assertTransform(transform, field = 'transform') {
+  if (transform === null || typeof transform !== 'object') {
+    throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, `${field} must be a transform object`, {
+      details: { field },
+    });
+  }
+  return createTransform(transform);
+}
+
+/**
+ * Compose two transforms: `b` is applied to the output of `a`.
+ *
+ * Requires a continuous space chain (`a.to === b.from`) and the same geometry version; otherwise
+ * the result would silently mix incompatible observations.
+ */
+export function composeTransforms(a, b) {
+  const first = assertTransform(a, 'a');
+  const second = assertTransform(b, 'b');
+  if (first.to !== second.from) {
+    throw new AdapterError(ERROR_CODES.CAPABILITY_UNSUPPORTED, 'cannot compose transforms across a space gap', {
+      details: { firstTo: first.to, secondFrom: second.from },
+    });
+  }
+  if (first.geometryVersion !== second.geometryVersion) {
+    throw new AdapterError(ERROR_CODES.CAPABILITY_UNSUPPORTED, 'cannot compose transforms from different geometry versions', {
+      details: { first: first.geometryVersion, second: second.geometryVersion },
+    });
+  }
+  return {
+    from: first.from,
+    to: second.to,
+    scaleX: first.scaleX * second.scaleX,
+    scaleY: first.scaleY * second.scaleY,
+    offsetX: first.offsetX * second.scaleX + second.offsetX,
+    offsetY: first.offsetY * second.scaleY + second.offsetY,
+    geometryVersion: first.geometryVersion,
+  };
+}
+
+/** Invert a transform. Zero scale is not invertible and reports CAPABILITY_UNSUPPORTED. */
+export function invertTransform(transform) {
+  const source = assertTransform(transform);
+  if (source.scaleX === 0 || source.scaleY === 0) {
+    throw new AdapterError(ERROR_CODES.CAPABILITY_UNSUPPORTED, 'transform has zero scale and cannot be inverted', {
+      details: { scaleX: source.scaleX, scaleY: source.scaleY },
+    });
+  }
+  return {
+    from: source.to,
+    to: source.from,
+    scaleX: 1 / source.scaleX,
+    scaleY: 1 / source.scaleY,
+    offsetX: -source.offsetX / source.scaleX,
+    offsetY: -source.offsetY / source.scaleY,
+    geometryVersion: source.geometryVersion,
+  };
+}
+
+/** Map one point through a transform. */
+export function mapPoint(transform, point) {
+  const source = assertTransform(transform);
+  const { x, y } = assertPoint(point);
+  return {
+    x: x * source.scaleX + source.offsetX,
+    y: y * source.scaleY + source.offsetY,
+  };
+}
+
+/**
+ * Map a rect through a transform. The result keeps non-negative width/height, so a flipped
+ * (negative-scale) mapping is still a usable rect.
+ */
+export function mapRect(transform, rect) {
+  const source = assertTransform(transform);
+  const { x, y, width, height } = assertRect(rect);
+  const x1 = x * source.scaleX + source.offsetX;
+  const x2 = (x + width) * source.scaleX + source.offsetX;
+  const y1 = y * source.scaleY + source.offsetY;
+  const y2 = (y + height) * source.scaleY + source.offsetY;
+  return {
+    x: Math.min(x1, x2),
+    y: Math.min(y1, y2),
+    width: Math.abs(x2 - x1),
+    height: Math.abs(y2 - y1),
+  };
+}
+
+/**
+ * Assert two mappings describe the same observation geometry, so results may be compared.
+ *
+ * - Different `from`/`to` spaces -> CAPABILITY_UNSUPPORTED (cannot compare across spaces).
+ * - Different `geometryVersion` -> GENERATION_MISMATCH (geometry changed under the same spaces).
+ */
+export function assertCompatibleMapping(a, b) {
+  const first = assertTransform(a, 'a');
+  const second = assertTransform(b, 'b');
+  if (first.from !== second.from || first.to !== second.to) {
+    throw new AdapterError(ERROR_CODES.CAPABILITY_UNSUPPORTED, 'mappings target different coordinate spaces', {
+      details: {
+        first: { from: first.from, to: first.to },
+        second: { from: second.from, to: second.to },
+      },
+    });
+  }
+  if (first.geometryVersion !== second.geometryVersion) {
+    throw new AdapterError(ERROR_CODES.GENERATION_MISMATCH, 'mappings belong to different geometry versions', {
+      details: { first: first.geometryVersion, second: second.geometryVersion },
+    });
+  }
+  return true;
+}

package/core/identity.js

@@ -0,0 +1,180 @@
+/**
+ * Neutral identity factories: scope, operation, target, session, generation.
+ *
+ * Rules (M0 §2.1 / §3):
+ * - Missing fields are `null`; identities never invent workspace ids, target ids or generations.
+ * - Operation summaries record shape only (types, lengths, counts), never argument plaintext.
+ * - Generation checks are explicit; a mismatch is a state error, not a silent retry.
+ */
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { ERROR_CODES } from './contracts.js';
+import { AdapterError } from './errors.js';
+
+function str(value) {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function finiteOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function integerOrNull(value) {
+  return Number.isInteger(value) ? value : null;
+}
+
+/** Summarize an argument bag without retaining any value plaintext. */
+export function summarizeArgs(args) {
+  if (args === undefined) return { type: 'undefined' };
+  if (args === null) return { type: 'null' };
+  if (typeof args === 'string') return { type: 'string', length: args.length };
+  if (typeof args === 'number') return { type: 'number' };
+  if (typeof args === 'boolean') return { type: 'boolean' };
+  if (typeof args === 'bigint') return { type: 'bigint' };
+  if (typeof args === 'function') return { type: 'function' };
+  if (Array.isArray(args)) return { type: 'array', length: args.length };
+  if (typeof args === 'object') {
+    const keys = Object.keys(args);
+    return { type: 'object', keys: keys.length };
+  }
+  return { type: typeof args };
+}
+
+let operationCounter = 0;
+
+function nextOperationId() {
+  operationCounter += 1;
+  return `op-${Date.now().toString(36)}-${operationCounter.toString(36)}`;
+}
+
+/**
+ * Stable workspace key shared by the config buckets and runtime entries.
+ *
+ * - Explicit workspace id wins: `workspace:<workspaceId>`.
+ * - Otherwise the normalized (realpath when possible) cwd is hashed: `path:<sha256 hex>`.
+ * - Missing identity returns null; nothing is invented.
+ *
+ * @param {{agent?:object, cwd?:string, workspaceId?:string}} [input]
+ * @returns {string|null}
+ */
+export function workspaceKeyOf({ agent = null, cwd = null, workspaceId = null } = {}) {
+  const explicitId = typeof workspaceId === 'string' && workspaceId.length > 0
+    ? workspaceId
+    : (typeof agent?.workspaceId === 'string' && agent.workspaceId.length > 0 ? agent.workspaceId : null);
+  if (explicitId !== null) return `workspace:${explicitId}`;
+
+  const rawCwd = typeof cwd === 'string' && cwd.length > 0
+    ? cwd
+    : (typeof agent?.session?.header?.cwd === 'string' && agent.session.header.cwd.length > 0
+      ? agent.session.header.cwd
+      : null);
+  if (rawCwd === null) return null;
+
+  let normalized;
+  try {
+    normalized = realpathSync(rawCwd);
+  } catch {
+    normalized = resolvePath(rawCwd);
+  }
+  const digest = createHash('sha256').update(normalized).digest('hex');
+  return `path:${digest}`;
+}
+
+/**
+ * @param {{id?:string, kind?:string, workspaceId?:string, cwd?:string, sessionId?:string}} [scope]
+ * @returns {{id:string|null, kind:string|null, workspaceId:string|null, cwd:string|null,
+ *   sessionId:string|null}}
+ */
+export function newScopeIdentity(scope = {}) {
+  const source = scope && typeof scope === 'object' ? scope : {};
+  return {
+    id: str(source.id),
+    kind: str(source.kind),
+    workspaceId: str(source.workspaceId),
+    cwd: str(source.cwd),
+    sessionId: str(source.sessionId),
+  };
+}
+
+/**
+ * @param {{tool?:string, args?:unknown, startedAt?:number|null, operationId?:string}} [input]
+ * @returns {{operationId:string, tool:string|null, argsSummary:object,
+ *   startedAt:number|null, finishedAt:null}}
+ */
+export function newOperation({ tool, args, startedAt, operationId } = {}) {
+  return {
+    operationId: str(operationId) ?? nextOperationId(),
+    tool: str(tool),
+    argsSummary: summarizeArgs(args),
+    startedAt: finiteOrNull(startedAt),
+    finishedAt: null,
+  };
+}
+
+/**
+ * @param {{targetId?:string, environment?:string, kind?:string, generation?:number,
+ *   label?:string, lifecycle?:string}} [input]
+ */
+export function newTargetIdentity({
+  targetId,
+  environment,
+  kind,
+  generation,
+  label,
+  lifecycle,
+} = {}) {
+  return {
+    targetId: str(targetId),
+    environment: str(environment),
+    kind: str(kind),
+    generation: integerOrNull(generation),
+    label: str(label),
+    lifecycle: str(lifecycle),
+  };
+}
+
+/**
+ * @param {{sessionId?:string, environment?:string, generation?:number,
+ *   configRevision?:number, targetId?:string}} [input]
+ */
+export function newSessionIdentity({
+  sessionId,
+  environment,
+  generation,
+  configRevision,
+  targetId,
+} = {}) {
+  return {
+    sessionId: str(sessionId),
+    environment: str(environment),
+    generation: integerOrNull(generation),
+    configRevision: integerOrNull(configRevision),
+    targetId: str(targetId),
+  };
+}
+
+/**
+ * Assert that a target/session is at the generation the caller observed.
+ *
+ * @param {{generation?:number}|number|null|undefined} target
+ * @param {number|null|undefined} expected
+ * @param {{code?:string}} [options]
+ * @returns {typeof target} the checked value, for chaining
+ */
+export function assertGeneration(target, expected, { code = ERROR_CODES.GENERATION_MISMATCH } = {}) {
+  const actual = target !== null && typeof target === 'object'
+    ? integerOrNull(target.generation)
+    : integerOrNull(target);
+  const wanted = integerOrNull(expected);
+  if (actual !== wanted) {
+    throw new AdapterError(code, `generation mismatch: expected ${String(wanted)}, got ${String(actual)}`, {
+      details: {
+        expected: wanted,
+        actual,
+        targetId: target !== null && typeof target === 'object' ? str(target.targetId) : null,
+      },
+    });
+  }
+  return target;
+}

package/core/index.js

@@ -0,0 +1,24 @@
+/**
+ * Public surface of the cross-environment core.
+ *
+ * Integration code imports from here; `core/` never imports index.js, targets/, browser-safety.js
+ * or any platform implementation. Every symbol below is a pure function, frozen data, or a class
+ * whose side effects are explicit (ConfigStore file I/O, AdapterRegistry.dispose).
+ */
+export * from './contracts.js';
+export * from './errors.js';
+export * from './identity.js';
+export * from './geometry.js';
+export * from './clock.js';
+export * from './evidence.js';
+export * from './config.js';
+export * from './config-store.js';
+export * from './registry.js';
+export * from './readiness.js';
+// P0 neutral models live in core/p0.js (separate write scope); the barrel exposes them so
+// adapters/providers have one import surface. No symbol names collide with the modules above.
+export * from './p0.js';
+// Team/page access model (M1): Principal, page-group keys, operation effects, control state
+// machine. Integration code imports it from this barrel; the module itself imports nothing but
+// `contracts.js`/`errors.js`, so authorisation stays testable without a browser or a Host.
+export * from './tab-access.js';