@tsplc/debug 0.0.0-stage → 0.2.17

package/dist/paths.js

@@ -0,0 +1,138 @@
+// packages/debug/src/paths.ts
+var segmentPattern = /[^.[\]]+|\[(?:-?\d+|\*)\]/g;
+var pathSegments = (path) => path.match(segmentPattern) ?? [];
+var joinPath = (prefix, segment) => segment.startsWith("[") || !prefix ? `${prefix}${segment}` : `${prefix}.${segment}`;
+var typeOf = (manifest, id) => manifest.types[id] ?? { kind: "scalar", iec: id };
+var createPaths = (manifest) => {
+  const typeOfId = (id) => typeOf(manifest, id);
+  const bases = new Map([
+    ...manifest.roots.map(({ path, ...root }) => [path, { kind: "target", path, ...root }]),
+    ...manifest.io.map(({ path, target, type }) => [path, { kind: "target", path, target, type, readable: true }])
+  ]);
+  const constants = new Map(manifest.constants.map(({ path, ...constant }) => [
+    path,
+    { kind: "constant", path, ...constant }
+  ]));
+  const groups = new Map;
+  for (const path of [...bases.keys(), ...constants.keys()]) {
+    let prefix = "";
+    for (const segment of pathSegments(path)) {
+      let children = groups.get(prefix);
+      if (!children)
+        groups.set(prefix, children = new Set);
+      children.add(segment);
+      prefix = joinPath(prefix, segment);
+    }
+  }
+  const resolve = (path) => {
+    const constant = constants.get(path);
+    if (constant)
+      return constant;
+    const segments = pathSegments(path);
+    for (let length = segments.length;length > 0; length--) {
+      const base = bases.get(segments.slice(0, length).reduce(joinPath, ""));
+      if (!base)
+        continue;
+      let resolved = base;
+      for (const segment of segments.slice(length)) {
+        const type = typeOfId(resolved.type);
+        if (type.kind === "record") {
+          const field = type.fields.find(({ name }) => name === segment);
+          if (!field)
+            return;
+          resolved = {
+            kind: "target",
+            path: joinPath(resolved.path, segment),
+            target: `${resolved.target}.${field.target}`,
+            type: field.type,
+            readable: resolved.readable,
+            ...field.generated && { generated: true },
+            ...field.declaration && { declaration: field.declaration }
+          };
+        } else if (type.kind === "array") {
+          const index = /^\[(-?\d+)\]$/.exec(segment)?.[1];
+          if (index === undefined || Number(index) < type.lower || Number(index) >= type.lower + type.length)
+            return;
+          resolved = {
+            kind: "target",
+            path: joinPath(resolved.path, segment),
+            target: `${resolved.target}[${index}]`,
+            type: type.element,
+            readable: resolved.readable
+          };
+        } else
+          return;
+      }
+      return resolved;
+    }
+  };
+  const typedChildren = (resolved) => {
+    const type = resolved?.kind === "target" ? typeOfId(resolved.type) : undefined;
+    if (type?.kind === "record")
+      return type.fields.map(({ name }) => name);
+    if (type?.kind === "array")
+      return Array.from({ length: type.length }, (_, index) => `[${type.lower + index}]`);
+    return [];
+  };
+  const children = (path) => {
+    const names = [...typedChildren(resolve(path)), ...groups.get(path) ?? []];
+    return [...new Set(names)].map((name) => {
+      const child = joinPath(path, name);
+      return { name, ...resolve(child) ?? { kind: "group", path: child } };
+    });
+  };
+  const isLeaf = (node) => node.kind === "constant" || node.kind === "target" && ["scalar", "enum"].includes(typeOfId(node.type).kind);
+  const expand = (patterns, limit = 2000) => {
+    const leaves = new Set;
+    const add = (path) => {
+      leaves.add(path);
+      if (leaves.size > limit)
+        throw new RangeError(`More than ${limit} values match`);
+    };
+    const below = (node) => {
+      if (isLeaf(node))
+        return add(node.path);
+      for (const child of children(node.path))
+        if (!(child.kind === "target" && child.generated))
+          below(child);
+    };
+    const match = (prefix, rest, wildcard) => {
+      const [head, ...tail] = rest;
+      if (head === undefined) {
+        const node = resolve(prefix) ?? (groups.has(prefix) ? { kind: "group", path: prefix } : undefined);
+        if (node)
+          below(node);
+        else if (!wildcard)
+          add(prefix);
+        return;
+      }
+      if (head === "*" || head === "[*]") {
+        for (const child of children(prefix))
+          if (!(child.kind === "target" && child.generated) && (head === "*" || child.name.startsWith("[")))
+            match(child.path, tail, true);
+      } else
+        match(joinPath(prefix, head), tail, wildcard);
+    };
+    for (const pattern of patterns)
+      match("", pathSegments(pattern), false);
+    return [...leaves];
+  };
+  const decode = (typeId, raw) => {
+    const type = typeOfId(typeId);
+    if (type.kind === "enum")
+      return Object.entries(type.members).find(([, value]) => value === raw)?.[0] ?? raw;
+    if (type.kind === "scalar" && type.iec === "BOOL" && typeof raw === "number")
+      return raw !== 0;
+    return raw;
+  };
+  return { typeOf: typeOfId, resolve, children, isLeaf, expand, decode };
+};
+export {
+  createPaths,
+  joinPath,
+  pathSegments,
+  typeOf
+};
+
+//# debugId=9B65CE7419829CA364756E2164756E21
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/paths.ts"],
+  "sourcesContent": [
+    "import type { DebugManifest, DebugType, SourceRange } from \"./manifest.ts\";\n\n/**\n * TypeScript paths over a manifest: `program.diverters.binTrackers[10].bin` names a root\n * (`program.diverters`), then record fields and array indexes. Pure, so the browser UI can use it.\n */\n\n/** A path that reads a target, or a constant the compiler folded. */\nexport type ResolvedPath =\n  | {\n      kind: \"target\";\n      path: string;\n      target: string;\n      type: string;\n      readable: boolean;\n      generated?: true;\n      declaration?: SourceRange;\n    }\n  | { kind: \"constant\"; path: string; type: string; value: unknown; declaration?: SourceRange };\n\n/** Roots or constants that share a prefix, such as `program` above `program.diverters`. */\ninterface GroupPath {\n  kind: \"group\";\n  path: string;\n}\n\n/** A child in the instance tree. */\nexport type PathNode = { name: string } & (ResolvedPath | GroupPath);\n\nconst segmentPattern = /[^.[\\]]+|\\[(?:-?\\d+|\\*)\\]/g;\n\nexport const pathSegments = (path: string) => path.match(segmentPattern) ?? [];\n\nexport const joinPath = (prefix: string, segment: string) =>\n  segment.startsWith(\"[\") || !prefix ? `${prefix}${segment}` : `${prefix}.${segment}`;\n\n/** Scalar type ids are their IEC names, and may have no entry in `types`. */\nexport const typeOf = (manifest: DebugManifest, id: string): DebugType =>\n  manifest.types[id] ?? { kind: \"scalar\", iec: id };\n\nexport const createPaths = (manifest: DebugManifest) => {\n  const typeOfId = (id: string) => typeOf(manifest, id);\n  // I/O bindings are readable symbols with TypeScript paths of their own.\n  const bases = new Map<string, Extract<ResolvedPath, { kind: \"target\" }>>([\n    ...manifest.roots.map(\n      ({ path, ...root }) => [path, { kind: \"target\" as const, path, ...root }] as const,\n    ),\n    ...manifest.io.map(\n      ({ path, target, type }) =>\n        [path, { kind: \"target\" as const, path, target, type, readable: true }] as const,\n    ),\n  ]);\n  const constants = new Map(\n    manifest.constants.map(({ path, ...constant }) => [\n      path,\n      { kind: \"constant\" as const, path, ...constant },\n    ]),\n  );\n  /** Children of the prefixes of every root and constant path, which are groups unless they resolve. */\n  const groups = new Map<string, Set<string>>();\n  for (const path of [...bases.keys(), ...constants.keys()]) {\n    let prefix = \"\";\n    for (const segment of pathSegments(path)) {\n      let children = groups.get(prefix);\n      if (!children) groups.set(prefix, (children = new Set()));\n      children.add(segment);\n      prefix = joinPath(prefix, segment);\n    }\n  }\n\n  const resolve = (path: string): ResolvedPath | undefined => {\n    const constant = constants.get(path);\n    if (constant) return constant;\n    const segments = pathSegments(path);\n    for (let length = segments.length; length > 0; length--) {\n      const base = bases.get(segments.slice(0, length).reduce(joinPath, \"\"));\n      if (!base) continue;\n      let resolved: ResolvedPath = base;\n      for (const segment of segments.slice(length)) {\n        const type = typeOfId(resolved.type);\n        if (type.kind === \"record\") {\n          const field = type.fields.find(({ name }) => name === segment);\n          if (!field) return;\n          resolved = {\n            kind: \"target\",\n            path: joinPath(resolved.path, segment),\n            target: `${resolved.target}.${field.target}`,\n            type: field.type,\n            readable: resolved.readable,\n            ...(field.generated && { generated: true }),\n            ...(field.declaration && { declaration: field.declaration }),\n          };\n        } else if (type.kind === \"array\") {\n          const index = /^\\[(-?\\d+)\\]$/.exec(segment)?.[1];\n          if (\n            index === undefined ||\n            Number(index) < type.lower ||\n            Number(index) >= type.lower + type.length\n          )\n            return;\n          resolved = {\n            kind: \"target\",\n            path: joinPath(resolved.path, segment),\n            target: `${resolved.target}[${index}]`,\n            type: type.element,\n            readable: resolved.readable,\n          };\n        } else return;\n      }\n      return resolved;\n    }\n  };\n\n  const typedChildren = (resolved: ResolvedPath | undefined) => {\n    const type = resolved?.kind === \"target\" ? typeOfId(resolved.type) : undefined;\n    if (type?.kind === \"record\") return type.fields.map(({ name }) => name);\n    if (type?.kind === \"array\")\n      return Array.from({ length: type.length }, (_, index) => `[${type.lower + index}]`);\n    return [];\n  };\n\n  /** A path's fields or indexes, and the roots and constants below it. */\n  const children = (path: string): PathNode[] => {\n    const names = [...typedChildren(resolve(path)), ...(groups.get(path) ?? [])];\n    return [...new Set(names)].map((name) => {\n      const child = joinPath(path, name);\n      return { name, ...(resolve(child) ?? { kind: \"group\", path: child }) };\n    });\n  };\n\n  const isLeaf = (node: ResolvedPath | GroupPath) =>\n    node.kind === \"constant\" ||\n    (node.kind === \"target\" && [\"scalar\", \"enum\"].includes(typeOfId(node.type).kind));\n\n  /**\n   * Leaf paths matching `patterns`, where `*` stands for one segment. A pattern naming a record,\n   * array or group stands for all its leaves; wildcards and expansion skip compiler-made fields.\n   * Paths that don't resolve are kept, so callers can report them.\n   */\n  const expand = (patterns: readonly string[], limit = 2000) => {\n    const leaves = new Set<string>();\n    const add = (path: string) => {\n      leaves.add(path);\n      if (leaves.size > limit) throw new RangeError(`More than ${limit} values match`);\n    };\n    const below = (node: ResolvedPath | GroupPath) => {\n      if (isLeaf(node)) return add(node.path);\n      for (const child of children(node.path))\n        if (!(child.kind === \"target\" && child.generated)) below(child);\n    };\n    const match = (prefix: string, rest: readonly string[], wildcard: boolean) => {\n      const [head, ...tail] = rest;\n      if (head === undefined) {\n        const node: ResolvedPath | GroupPath | undefined =\n          resolve(prefix) ?? (groups.has(prefix) ? { kind: \"group\", path: prefix } : undefined);\n        if (node) below(node);\n        else if (!wildcard) add(prefix);\n        return;\n      }\n      if (head === \"*\" || head === \"[*]\") {\n        for (const child of children(prefix))\n          if (\n            !(child.kind === \"target\" && child.generated) &&\n            (head === \"*\" || child.name.startsWith(\"[\"))\n          )\n            match(child.path, tail, true);\n      } else match(joinPath(prefix, head), tail, wildcard);\n    };\n    for (const pattern of patterns) match(\"\", pathSegments(pattern), false);\n    return [...leaves];\n  };\n\n  /** A value as TypeScript shows it: enum members by name, BOOL as a boolean. */\n  const decode = (typeId: string, raw: unknown) => {\n    const type = typeOfId(typeId);\n    if (type.kind === \"enum\")\n      return Object.entries(type.members).find(([, value]) => value === raw)?.[0] ?? raw;\n    if (type.kind === \"scalar\" && type.iec === \"BOOL\" && typeof raw === \"number\") return raw !== 0;\n    return raw;\n  };\n\n  return { typeOf: typeOfId, resolve, children, isLeaf, expand, decode };\n};\n\nexport type Paths = ReturnType<typeof createPaths>;\n"
+  ],
+  "mappings": "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",
+  "debugId": "9B65CE7419829CA364756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@tsplc/debug",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.17",
+  "type": "module",
+  "license": "MIT",
+  "description": "Debugger for tsPLC programs: live TypeScript variables, hardware, async jobs, backend requests and the program's recent telemetry.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/livingforjesus/tsplc.git",
+    "directory": "packages/debug"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./src/manifest.ts",
+      "bun": "./src/manifest.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./format": {
+      "types": "./src/ui/format.ts",
+      "bun": "./src/ui/format.ts",
+      "default": "./dist/format.js"
+    },
+    "./paths": {
+      "types": "./src/paths.ts",
+      "bun": "./src/paths.ts",
+      "default": "./dist/paths.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tsplc/config": "0.2.17",
+    "@tsplc/opcua": "0.2.17",
+    "@tsplc/server": "0.2.17",
+    "zod": "4.3.6"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,59 @@
+import type { ConnectionState, Quality } from "./api.ts";
+import type { DebugType } from "./manifest.ts";
+
+/** One target's value, before the debugger names it by TypeScript path and decodes it. */
+export interface TargetSample {
+  value: unknown;
+  quality: Quality;
+  status: string;
+  receivedAt: string;
+}
+
+/** A target to read, with its type in the manifest, which an adapter may need to parse it. */
+export interface TargetRead {
+  target: string;
+  type: DebugType;
+}
+
+const qualityRank: Record<Quality, number> = { good: 0, uncertain: 1, bad: 2, unavailable: 3 };
+
+/** The worst of these qualities; nothing read is unavailable. */
+export const worstQuality = (samples: readonly (TargetSample | undefined)[]): Quality =>
+  samples.reduce<Quality>((worst, sample) => {
+    const quality = sample?.quality ?? "unavailable";
+    return qualityRank[quality] > qualityRank[worst] ? quality : worst;
+  }, "good");
+
+export interface Connection {
+  state: ConnectionState;
+  since: string;
+  error?: string;
+}
+
+/**
+ * Reads one vendor's controller. Only the adapter interprets `target` strings, which come from
+ * the manifest (for CODESYS, IEC symbol paths). It never writes.
+ */
+export interface TargetAdapter {
+  /** How it reads, for display, such as "engineering login". */
+  readonly method: string;
+  /** Where it reads, for display. */
+  readonly endpoint: string;
+  /** How often subscribed targets are read; a value is at most about this old while connected. */
+  readonly samplingMs: number;
+  connection(): Connection;
+  onConnection(listener: (connection: Connection) => void): () => void;
+  /** Reads targets now; fails while disconnected. Targets that can't be read come back bad or unavailable. */
+  read(targets: readonly TargetRead[]): Promise<Map<string, TargetSample>>;
+  /**
+   * Calls `listener` with each target's value, about every `intervalMs` (`samplingMs` by
+   * default) or on every change, across reconnects, until the returned function is called. While
+   * disconnected each target is reported unavailable or bad.
+   */
+  subscribe(
+    targets: readonly TargetRead[],
+    listener: (target: string, sample: TargetSample) => void,
+    intervalMs?: number,
+  ): () => void;
+  close(): Promise<void>;
+}

package/src/api.ts

@@ -0,0 +1,182 @@
+import type { AppRecord } from "@tsplc/server/telemetry";
+import type { DebugManifest, SourceRange } from "./manifest.ts";
+
+/**
+ * The debugger API's response shapes, shared by the host, the browser UI and the VS Code extension.
+ * Routes are listed in docs/design/debugging.md; streams are Server-Sent Events whose event names are
+ * the keys of `StreamEvents`.
+ */
+
+export type Quality = "good" | "uncertain" | "bad" | "unavailable";
+
+/** One value as read. Values of different paths may come from different scans. */
+export interface Sample {
+  path: string;
+  value: unknown;
+  quality: Quality;
+  status: string;
+  /** When the debugger host received it; the controller reports no time of its own. */
+  receivedAt: string;
+}
+
+/** `unavailable`: nothing to read through, such as no engineering login open. */
+export type ConnectionState = "connecting" | "connected" | "lost" | "failed" | "unavailable";
+
+export interface Session {
+  build: { manifest: string | null; controller: string | null; matches: boolean };
+  connection: { state: ConnectionState; since: string; endpoint: string; error?: string };
+  /** How live values are read, such as "engineering login", and how often. */
+  reading: { method: string; intervalMs: number };
+  /** From the tasks' telemetry batches; `dropped` counts records overwritten before they were sent. */
+  tasks: { name: string; scan: number | null; scansPerSecond: number | null; dropped: number }[];
+  /** PLC clock minus the app server's clock, estimated from telemetry batches. */
+  clock: { offsetMs: number; uncertaintyMs: number } | null;
+  release?: { id: string; deployedAt: string; operation: string };
+  /** The project directory on the host, when served by `tsplc debug`. */
+  projectRoot?: string;
+}
+
+/** A trace record, decoded through the manifest's event sites. */
+export interface TraceEvent {
+  sequence: number;
+  task: string;
+  scan: number;
+  plcTime: number;
+  site: number;
+  value: unknown;
+  /** The site's guard operands, in the site's order. */
+  operands: { text: string; path?: string; stable: boolean; value: unknown }[];
+}
+
+export type { AppRecord };
+
+export interface RequestTrace {
+  /** The server's own sequence number. */
+  seq: number;
+  service: string;
+  /** From `x-tsplc-request: <job id>:<sequence>`. */
+  job?: number;
+  sequence?: number;
+  startedAt: string;
+  durationMs?: number;
+  status: "pending" | "ok" | "error" | "timeout";
+  httpStatus?: number;
+  error?: string;
+  input?: unknown;
+  output?: unknown;
+}
+
+/**
+ * A job as last seen. `busy` is null until it is known: from the trace's start and finish
+ * records, or read through the login while a page shows the job. The rest is read only while it
+ * is busy and shown.
+ */
+export interface JobState {
+  id: number;
+  /** Of the `busy` reading; a traced job's is good. */
+  quality: Quality;
+  busy: boolean | null;
+  cancelling?: boolean;
+  step?: number;
+  current?: { kind: string; range: SourceRange; text: string };
+  startedAt?: string;
+  elapsedMs?: number;
+  request?: { service: string; sequence: number; trace?: RequestTrace };
+  /** Busy, but over the number of jobs whose details are read on each poll. */
+  unread?: true;
+  /** The last failure nothing caught, from the program's `exception` records. */
+  failure?: { at: string; code: number; name?: string; source: string };
+}
+
+export interface DeviceState {
+  id: string;
+  /** "unknown" unless the driver's own state was read. */
+  health: {
+    state: "unknown" | "ok" | "fault" | "stale";
+    value?: number;
+    name?: string;
+    diagnostic?: boolean;
+    message?: string;
+    quality: Quality;
+  };
+  assemblies: {
+    direction: "input" | "output";
+    address?: string;
+    bytes: number[] | null;
+    quality: Quality;
+  }[];
+  /** Channels bound to TypeScript I/O paths, by channel id. */
+  channels: { id: string; path: string; value: unknown; quality: Quality }[];
+  /** The device's hand-configured status symbols, by label. */
+  status: Record<string, { value: unknown; quality: Quality }>;
+}
+
+/** An entry of the "Recent" view: the server's recent window, merged with the agent's logs. */
+export type TimelineEntry = {
+  at: string;
+  /** Placed through another clock (the PLC's, or the app server's), so its order is approximate. */
+  approximate: boolean;
+  source: "plc" | "server" | "agent" | "debugger";
+} & (
+  | { kind: "app"; task: string; sequence: number; record: AppRecord }
+  | { kind: "trace"; trace: TraceEvent }
+  | { kind: "request"; request: RequestTrace }
+  | {
+      kind: "deploy";
+      release: string;
+      operation: string;
+      build?: string;
+      user?: string;
+      host?: string;
+    }
+  | {
+      kind: "audit";
+      /** As typed after `tsplc`, such as `force` or `reset cold`. */
+      command: string;
+      /** Expressions written or forced, with their values; unforced expressions map to "". */
+      values: Record<string, string>;
+      /** The values read just before a write or force. */
+      previous?: Record<string, string>;
+      user?: string;
+      host?: string;
+      release?: string;
+      error?: string;
+    }
+  | { kind: "connection"; state: ConnectionState; error?: string }
+);
+
+export interface WatchGroups {
+  groups: Record<string, string[]>;
+}
+
+/**
+ * What a page shows, so the host reads only that: `watch` paths, `jobs` by id, the health of
+ * `health` devices, and everything of `devices`. Stream query parameters, comma-separated.
+ */
+export interface Interest {
+  watch: string[];
+  jobs: number[];
+  health: string[];
+  devices: string[];
+}
+
+export interface StreamEvents {
+  session: Session;
+  sample: Sample;
+  job: JobState;
+  request: RequestTrace;
+  device: DeviceState;
+  timeline: TimelineEntry;
+}
+
+/** Response bodies by route. Errors are `{ error: string }` with a 4xx or 5xx status. */
+export interface ApiResponses {
+  "GET /api/session": Session;
+  "GET /api/manifest": DebugManifest;
+  "GET /api/values": Sample[];
+  "GET /api/jobs": JobState[];
+  "GET /api/hardware": DeviceState[];
+  "GET /api/timeline": TimelineEntry[];
+  "GET /api/watch": WatchGroups;
+  "PUT /api/watch": WatchGroups;
+}