@filsilva/helios-cli 0.10.0

package/src/daemon/entry.js

@@ -0,0 +1,36 @@
+const rawConfig = process.argv[2];
+if (!rawConfig) {
+  throw new Error('Missing daemon configuration payload');
+}
+
+const config = JSON.parse(Buffer.from(rawConfig, 'base64url').toString('utf8'));
+if (config.storageDir) process.env.HELIOS_CLI_STORAGE_DIR = config.storageDir;
+
+const { SessionDaemon } = await import('./SessionDaemon.js');
+const { saveSessionMeta } = await import('../shared/sessionRegistry.js');
+const daemon = new SessionDaemon(config);
+
+try {
+  await daemon.start();
+} catch (error) {
+  await saveSessionMeta(config.sessionId, {
+    sessionId: config.sessionId,
+    pid: process.pid,
+    status: 'error',
+    mode: config.mode,
+    renderer: config.renderer,
+    layout: config.layout,
+    runtime: config.runtime,
+    surface: config.surface ?? null,
+    client: config.client ?? null,
+    browserChannel: config.browserChannel ?? null,
+    noGpu: config.noGpu === true,
+    bridgeConnected: false,
+    gpu: error?.data ?? null,
+    networkPath: config.networkPath ?? null,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    lastError: error?.stack ?? error?.message ?? String(error),
+  });
+  throw error;
+}

package/src/protocol/jsonl.js

@@ -0,0 +1,88 @@
+import { once } from 'node:events';
+
+export function encodeMessage(message) {
+  return `${JSON.stringify(message)}\n`;
+}
+
+export function createJsonLineParser(onMessage) {
+  let buffer = '';
+  return (chunk) => {
+    buffer += chunk;
+    while (true) {
+      const lineEnd = buffer.indexOf('\n');
+      if (lineEnd === -1) break;
+      const line = buffer.slice(0, lineEnd).trim();
+      buffer = buffer.slice(lineEnd + 1);
+      if (!line) continue;
+      const parsed = JSON.parse(line);
+      onMessage(parsed);
+    }
+  };
+}
+
+export function writeJsonLine(stream, value) {
+  stream.write(encodeMessage(value));
+}
+
+export async function callJsonRpc(stream, reader, payload, { timeoutMs = 30_000 } = {}) {
+  const id = payload.id;
+  const response = await reader.waitForResponse(id, { timeoutMs }, () => {
+    writeJsonLine(stream, payload);
+  });
+  if (response?.error) {
+    const error = new Error(response.error.message ?? 'RPC request failed');
+    error.code = response.error.code;
+    error.data = response.error.data;
+    throw error;
+  }
+  return response?.result;
+}
+
+export class JsonRpcResponseReader {
+  constructor() {
+    this.pending = new Map();
+    this.notifications = new Set();
+  }
+
+  onNotification(handler) {
+    this.notifications.add(handler);
+    return () => this.notifications.delete(handler);
+  }
+
+  handleMessage(message) {
+    if (Object.prototype.hasOwnProperty.call(message ?? {}, 'id') && this.pending.has(message.id)) {
+      const pending = this.pending.get(message.id);
+      this.pending.delete(message.id);
+      pending.resolve(message);
+      return;
+    }
+    for (const handler of this.notifications) handler(message);
+  }
+
+  waitForResponse(id, { timeoutMs = 30_000 } = {}, send) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timed out waiting for RPC response ${id}`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timeout);
+          resolve(value);
+        },
+      });
+      try {
+        send();
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pending.delete(id);
+        reject(error);
+      }
+    });
+  }
+}
+
+export async function pipeStreams(source, destination) {
+  source.pipe(destination);
+  await once(source, 'close');
+}

package/src/shared/cliConfig.js

@@ -0,0 +1,52 @@
+import path from 'node:path';
+import { ensureStateDirs, readJsonFile, writeJsonFile } from './fs.js';
+import { cliConfigPath } from './paths.js';
+
+const defaultConfig = Object.freeze({
+  version: 1,
+  apps: {},
+});
+
+function normalizeConfig(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { ...defaultConfig, apps: {} };
+  const apps = value.apps && typeof value.apps === 'object' && !Array.isArray(value.apps)
+    ? { ...value.apps }
+    : {};
+  return {
+    version: Number.isInteger(value.version) ? value.version : 1,
+    ...value,
+    apps,
+  };
+}
+
+export async function loadCliConfig() {
+  await ensureStateDirs();
+  return normalizeConfig(await readJsonFile(cliConfigPath, defaultConfig));
+}
+
+export async function saveCliConfig(config) {
+  await ensureStateDirs();
+  const normalized = normalizeConfig(config);
+  await writeJsonFile(cliConfigPath, normalized);
+  return normalized;
+}
+
+export async function getConfiguredDesktopAppPath() {
+  const config = await loadCliConfig();
+  const value = config.apps?.desktop?.appPath;
+  return value == null ? null : String(value);
+}
+
+export async function setConfiguredDesktopAppPath(appPath) {
+  const resolvedPath = path.resolve(String(appPath));
+  const config = await loadCliConfig();
+  config.apps = config.apps ?? {};
+  config.apps.desktop = {
+    ...(config.apps.desktop && typeof config.apps.desktop === 'object' ? config.apps.desktop : {}),
+    appPath: resolvedPath,
+  };
+  await saveCliConfig(config);
+  return resolvedPath;
+}
+
+export { cliConfigPath };

package/src/shared/fileSessionStore.js

@@ -0,0 +1,202 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ensureStateDirs, readJsonFile, writeJsonFile } from './fs.js';
+import {
+  sessionIndexPath,
+  sessionNetworksDir,
+  sessionPositionsDir,
+  sessionRecordsDir,
+  unfinishedSessionsPath,
+} from './paths.js';
+
+function filenameForId(id, extension = '.json') {
+  return `${Buffer.from(String(id), 'utf8').toString('base64url')}${extension}`;
+}
+
+function recordPath(id) {
+  return path.join(sessionRecordsDir, filenameForId(id));
+}
+
+function sidecarPath(directory, sessionId, extension) {
+  return path.join(directory, filenameForId(sessionId, extension));
+}
+
+function asUint8Array(value) {
+  if (value == null) return null;
+  if (value instanceof Uint8Array) return value;
+  if (Buffer.isBuffer(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (value.__heliosBinary === 'base64') return new Uint8Array(Buffer.from(String(value.data ?? ''), 'base64'));
+  return null;
+}
+
+export function encodeBinaryForJson(value) {
+  if (value == null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((entry) => encodeBinaryForJson(entry));
+  const bytes = asUint8Array(value);
+  if (bytes) {
+    return {
+      __heliosBinary: 'base64',
+      type: value.constructor?.name ?? 'Uint8Array',
+      byteLength: bytes.byteLength,
+      data: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64'),
+    };
+  }
+  const output = {};
+  for (const [key, entry] of Object.entries(value)) output[key] = encodeBinaryForJson(entry);
+  return output;
+}
+
+export function decodeBinaryFromJson(value) {
+  if (value == null || typeof value !== 'object') return value;
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value) || Buffer.isBuffer(value)) return value;
+  if (value.__heliosBinary === 'base64') {
+    return new Uint8Array(Buffer.from(String(value.data ?? ''), 'base64'));
+  }
+  if (Array.isArray(value)) return value.map((entry) => decodeBinaryFromJson(entry));
+  const output = {};
+  for (const [key, entry] of Object.entries(value)) output[key] = decodeBinaryFromJson(entry);
+  return output;
+}
+
+function networkExtension(format) {
+  const normalized = String(format ?? 'zxnet').trim().toLowerCase().replace(/^\./, '');
+  if (normalized === 'bxnet') return '.bxnet';
+  if (normalized === 'xnet') return '.xnet';
+  return '.zxnet';
+}
+
+async function readIndex() {
+  const parsed = await readJsonFile(sessionIndexPath, []);
+  return Array.isArray(parsed) ? parsed.map((id) => String(id)).filter(Boolean) : [];
+}
+
+async function writeIndex(ids) {
+  await writeJsonFile(sessionIndexPath, Array.from(new Set(ids.map((id) => String(id)).filter(Boolean))));
+}
+
+async function addToIndex(id) {
+  if (!id) return;
+  const ids = await readIndex();
+  if (!ids.includes(String(id))) await writeIndex([...ids, String(id)]);
+}
+
+async function removeFromIndex(id) {
+  if (!id) return;
+  const target = String(id);
+  await writeIndex((await readIndex()).filter((entry) => entry !== target));
+}
+
+async function unlinkIfExists(filePath) {
+  try {
+    await fs.unlink(filePath);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+function sidecarMetadata(record, dataFile, byteLength) {
+  const { data, ...metadata } = record;
+  return {
+    ...metadata,
+    data: null,
+    dataFile,
+    byteLength: Number.isFinite(Number(record.byteLength)) ? Number(record.byteLength) : byteLength,
+    updatedAt: record.updatedAt ?? Date.now(),
+  };
+}
+
+export class FileSessionStore {
+  async putSession(record) {
+    await ensureStateDirs();
+    const decoded = decodeBinaryFromJson(record);
+    const id = decoded?.id;
+    if (!id) throw new Error('Session record requires an id');
+
+    if (decoded.kind === 'session-network-data') {
+      const bytes = asUint8Array(decoded.data);
+      if (!bytes) throw new Error(`Network side record ${id} is missing binary data`);
+      const filePath = sidecarPath(sessionNetworksDir, decoded.sessionId ?? id, networkExtension(decoded.format));
+      await fs.writeFile(filePath, Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+      const metadata = sidecarMetadata(decoded, filePath, bytes.byteLength);
+      await writeJsonFile(recordPath(id), encodeBinaryForJson(metadata));
+      return encodeBinaryForJson(metadata);
+    }
+
+    if (decoded.kind === 'session-position-data') {
+      const bytes = asUint8Array(decoded.data);
+      if (!bytes) throw new Error(`Position side record ${id} is missing binary data`);
+      const filePath = sidecarPath(sessionPositionsDir, decoded.sessionId ?? id, '.positions.bin');
+      await fs.writeFile(filePath, Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+      const metadata = sidecarMetadata(decoded, filePath, bytes.byteLength);
+      await writeJsonFile(recordPath(id), encodeBinaryForJson(metadata));
+      return encodeBinaryForJson(metadata);
+    }
+
+    await writeJsonFile(recordPath(id), encodeBinaryForJson(decoded));
+    await addToIndex(id);
+    return encodeBinaryForJson(decoded);
+  }
+
+  async getSession(id) {
+    await ensureStateDirs();
+    const record = decodeBinaryFromJson(await readJsonFile(recordPath(id), null));
+    if (!record) return null;
+    if ((record.kind === 'session-network-data' || record.kind === 'session-position-data') && record.dataFile) {
+      try {
+        const bytes = await fs.readFile(record.dataFile);
+        record.data = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        record.byteLength = record.byteLength ?? bytes.byteLength;
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+        record.data = null;
+      }
+    }
+    return encodeBinaryForJson(record);
+  }
+
+  async listSessions() {
+    await ensureStateDirs();
+    const records = [];
+    for (const id of await readIndex()) {
+      const record = await this.getSession(id);
+      if (record) records.push(record);
+    }
+    return records;
+  }
+
+  async deleteSession(id) {
+    await ensureStateDirs();
+    const session = decodeBinaryFromJson(await readJsonFile(recordPath(id), null));
+    const networkId = session?.payload?.networkData?.dataRef ?? `${id}::network-data`;
+    const positionId = session?.payload?.positionData?.dataRef ?? `${id}::position-data`;
+    const network = decodeBinaryFromJson(await readJsonFile(recordPath(networkId), null));
+    const position = decodeBinaryFromJson(await readJsonFile(recordPath(positionId), null));
+    await Promise.all([
+      unlinkIfExists(recordPath(id)),
+      unlinkIfExists(recordPath(networkId)),
+      unlinkIfExists(recordPath(positionId)),
+      network?.dataFile ? unlinkIfExists(network.dataFile) : Promise.resolve(),
+      position?.dataFile ? unlinkIfExists(position.dataFile) : Promise.resolve(),
+    ]);
+    await removeFromIndex(id);
+    return true;
+  }
+
+  async getUnfinishedSessionId(workspaceId = null) {
+    const records = await readJsonFile(unfinishedSessionsPath, {});
+    const key = workspaceId == null || workspaceId === '' ? 'default' : String(workspaceId);
+    return records?.[key] ?? null;
+  }
+
+  async setUnfinishedSessionId(id, workspaceId = null) {
+    await ensureStateDirs();
+    const records = await readJsonFile(unfinishedSessionsPath, {});
+    const key = workspaceId == null || workspaceId === '' ? 'default' : String(workspaceId);
+    if (id == null || id === '') delete records[key];
+    else records[key] = String(id);
+    await writeJsonFile(unfinishedSessionsPath, records);
+    return id ?? null;
+  }
+}

package/src/shared/fs.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs/promises';
+import {
+  clientDistDir,
+  logsDir,
+  sessionNetworksDir,
+  sessionPositionsDir,
+  sessionRecordsDir,
+  sessionsDir,
+  sessionStateDir,
+  socketsDir,
+  stateRoot,
+  storageSessionsDir,
+} from './paths.js';
+
+export async function ensureStateDirs() {
+  await Promise.all([
+    fs.mkdir(stateRoot, { recursive: true }),
+    fs.mkdir(sessionsDir, { recursive: true }),
+    fs.mkdir(sessionStateDir, { recursive: true }),
+    fs.mkdir(socketsDir, { recursive: true }),
+    fs.mkdir(logsDir, { recursive: true }),
+    fs.mkdir(storageSessionsDir, { recursive: true }),
+    fs.mkdir(sessionRecordsDir, { recursive: true }),
+    fs.mkdir(sessionNetworksDir, { recursive: true }),
+    fs.mkdir(sessionPositionsDir, { recursive: true }),
+  ]);
+}
+
+export async function ensureClientBundle() {
+  try {
+    const stat = await fs.stat(clientDistDir);
+    if (!stat.isDirectory()) {
+      throw new Error(`Client bundle path is not a directory: ${clientDistDir}`);
+    }
+  } catch (error) {
+    throw new Error(
+      `Missing built client bundle at ${clientDistDir}. Run "npm run build-client" in helios-cli before starting sessions.`,
+      { cause: error },
+    );
+  }
+}
+
+export async function readJsonFile(filePath, fallback = null) {
+  try {
+    const text = await fs.readFile(filePath, 'utf8');
+    if (text.trim() === '') return fallback;
+    return JSON.parse(text);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return fallback;
+    if (error instanceof SyntaxError) return fallback;
+    throw error;
+  }
+}
+
+export async function writeJsonFile(filePath, value) {
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmpPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  await fs.rename(tmpPath, filePath);
+}

package/src/shared/networkFormats.js

@@ -0,0 +1,55 @@
+export const HELIOS_NETWORK_FORMATS = Object.freeze({
+  bxnet: Object.freeze({
+    id: 'bxnet',
+    extension: '.bxnet',
+    mimeType: 'application/vnd.helios.bxnet',
+    label: 'Helios Binary Network',
+  }),
+  zxnet: Object.freeze({
+    id: 'zxnet',
+    extension: '.zxnet',
+    mimeType: 'application/vnd.helios.zxnet',
+    label: 'Helios Compressed Network',
+  }),
+  xnet: Object.freeze({
+    id: 'xnet',
+    extension: '.xnet',
+    mimeType: 'application/vnd.helios.xnet',
+    label: 'Helios XNet Network',
+  }),
+  gml: Object.freeze({
+    id: 'gml',
+    extension: '.gml',
+    mimeType: 'application/gml+xml',
+    label: 'Graph Modeling Language Network',
+  }),
+  gt: Object.freeze({
+    id: 'gt',
+    extension: '.gt',
+    extensions: Object.freeze(['.gt', '.gt.zst']),
+    mimeType: 'application/vnd.graph-tool.gt',
+    label: 'Graph-tool Network',
+  }),
+});
+
+export const HELIOS_NETWORK_EXTENSIONS = Object.freeze(
+  Object.values(HELIOS_NETWORK_FORMATS).flatMap((entry) => entry.extensions ?? [entry.extension]),
+);
+
+export function inferNetworkFormat(filePath, fallback = 'bxnet') {
+  const normalizedPath = String(filePath ?? '').toLowerCase();
+  for (const format of Object.values(HELIOS_NETWORK_FORMATS)) {
+    const extensions = format.extensions ?? [format.extension];
+    if (extensions.some((extension) => normalizedPath.endsWith(extension))) return format.id;
+  }
+  return fallback;
+}
+
+export function isHeliosNetworkPath(filePath) {
+  const normalizedPath = String(filePath ?? '').toLowerCase();
+  return HELIOS_NETWORK_EXTENSIONS.some((extension) => normalizedPath.endsWith(extension));
+}
+
+export function networkMimeTypeForFormat(format) {
+  return HELIOS_NETWORK_FORMATS[format]?.mimeType ?? 'application/octet-stream';
+}

package/src/shared/networkInspect.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import HeliosNetwork, { AttributeType } from 'helios-network';
+import { inferNetworkFormat } from './networkFormats.js';
+
+const ATTRIBUTE_TYPE_NAMES = new Map(
+  Object.entries(AttributeType).map(([name, value]) => [value, name]),
+);
+
+function attributeTypeName(type) {
+  return ATTRIBUTE_TYPE_NAMES.get(type) ?? `Unknown(${type})`;
+}
+
+function serializeAttributeInfo(name, info) {
+  const type = info?.type ?? AttributeType.Unknown;
+  return {
+    name,
+    type,
+    typeName: attributeTypeName(type),
+    dimension: Number(info?.dimension ?? 1),
+    complex: info?.complex === true,
+    categorical: type === AttributeType.Category || type === AttributeType.MultiCategory,
+    stringLike: type === AttributeType.String,
+  };
+}
+
+function inspectAttributes(network, scope) {
+  const namesMethod = `get${scope}AttributeNames`;
+  const infoMethod = `get${scope}AttributeInfo`;
+  const names = typeof network?.[namesMethod] === 'function' ? network[namesMethod]() : [];
+  return names.map((name) => serializeAttributeInfo(name, network?.[infoMethod]?.(name)));
+}
+
+async function loadNetwork(bytes, format, options = {}) {
+  if (format === 'bxnet') return HeliosNetwork.fromBXNet(bytes, options);
+  if (format === 'zxnet') return HeliosNetwork.fromZXNet(bytes, options);
+  if (format === 'xnet') return HeliosNetwork.fromXNet(bytes, options);
+  if (format === 'gt') return HeliosNetwork.fromGT(bytes, options);
+  throw new Error(`Unsupported Helios network format "${format}"`);
+}
+
+export async function inspectNetworkFile(filePath, options = {}) {
+  const resolvedPath = path.resolve(filePath);
+  const format = options.format ?? inferNetworkFormat(resolvedPath, null);
+  if (!format) throw new Error(`Cannot infer Helios network format from "${filePath}"`);
+
+  const warnings = [];
+  const originalWarn = console.warn;
+  let network = null;
+  try {
+    const stat = await fs.stat(resolvedPath);
+    const bytes = await fs.readFile(resolvedPath);
+    console.warn = (...args) => {
+      const message = args.map((entry) => String(entry)).join(' ');
+      if (message.includes('[Helios serialization]')) warnings.push(message);
+      else originalWarn(...args);
+    };
+    network = await loadNetwork(new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength), format, options.loadOptions ?? {});
+    return {
+      kind: 'helios-network-inspection',
+      version: 1,
+      path: resolvedPath,
+      name: path.basename(resolvedPath),
+      format,
+      fileSize: stat.size,
+      modifiedAt: stat.mtime.toISOString(),
+      nodeCount: network.nodeCount ?? 0,
+      edgeCount: network.edgeCount ?? 0,
+      directed: Boolean(network.directed),
+      attributes: {
+        node: inspectAttributes(network, 'Node'),
+        edge: inspectAttributes(network, 'Edge'),
+        network: inspectAttributes(network, 'Network'),
+      },
+      warnings,
+    };
+  } finally {
+    console.warn = originalWarn;
+    network?.dispose?.();
+  }
+}

package/src/shared/paths.js

@@ -0,0 +1,43 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const packageRoot = path.resolve(__dirname, '..', '..');
+export const clientDistDir = path.join(packageRoot, 'dist', 'client');
+export const stateRoot = path.resolve(
+  process.env.HELIOS_CLI_STORAGE_DIR
+    ?? process.env.HELIOS_HOME
+    ?? path.join(os.homedir(), '.helios'),
+);
+export const runtimeDir = path.join(stateRoot, 'runtime');
+export const sessionsDir = path.join(runtimeDir, 'sessions');
+export const sessionStateDir = path.join(runtimeDir, 'session-state');
+export const socketsDir = path.join(runtimeDir, 'sockets');
+export const logsDir = path.join(runtimeDir, 'logs');
+export const storageSessionsDir = path.join(stateRoot, 'sessions');
+export const sessionRecordsDir = path.join(storageSessionsDir, 'records');
+export const sessionNetworksDir = path.join(storageSessionsDir, 'networks');
+export const sessionPositionsDir = path.join(storageSessionsDir, 'positions');
+export const sessionIndexPath = path.join(storageSessionsDir, 'index.json');
+export const unfinishedSessionsPath = path.join(storageSessionsDir, 'unfinished.json');
+export const cliConfigPath = path.join(stateRoot, 'config.json');
+
+export function sessionMetaPath(sessionId) {
+  return path.join(sessionsDir, `${sessionId}.json`);
+}
+
+export function sessionStatePath(sessionId) {
+  return path.join(sessionStateDir, `${sessionId}.json`);
+}
+
+export function sessionSocketPath(sessionId) {
+  if (process.platform === 'win32') {
+    return `\\\\.\\pipe\\helios-cli-${sessionId}`;
+  }
+  const candidate = path.join(socketsDir, `${sessionId}.sock`);
+  if (Buffer.byteLength(candidate, 'utf8') < 100) return candidate;
+  return path.join(os.tmpdir(), 'helios-cli-sockets', `${sessionId}.sock`);
+}