spark/readme.hints.md

Project Memory: @serve.zone/spark

Project Overview

• Purpose: Cluster node server system manager used by @serve.zone/cloudly
• Runtime: Deno 2.x - this is a Deno-based project, NOT Node.js
• Configuration: Uses deno.json for dependencies and tasks
• Main entry: mod.ts for CLI, exports from ts/index.ts

Architecture

• SparkConfig: Key-value store for configuration (npmextra.KeyValueStore)
• SparkTaskManager: Cron-based task scheduling (taskbuffer.TaskManager)
• SparkServicesManager: Docker service management via @apiclient.xyz/docker
• SmartDaemon: Systemd integration for daemon mode

Key Dependencies (Updated Feb 2026)

• @apiclient.xyz/docker@^5.1.0 - Docker API (Facade pattern with DockerHost as entry point)
• @serve.zone/api@^5.3.0 - Serve.zone API client
• @serve.zone/interfaces@^5.3.0 - Type definitions
• @push.rocks/taskbuffer@^3.0.10 - Task scheduling
• @push.rocks/smartdaemon@^2.1.0 - Systemd service management
• @push.rocks/smartcli@^4.0.20 - CLI framework

Docker API Notes (v5.x)

The @apiclient.xyz/docker package uses a Facade pattern. All operations go through DockerHost:

• dockerHost.getServiceByName(name) - Get service by name
• dockerHost.getSecretByName(name) - Get secret by name
• dockerHost.createImageFromRegistry({ imageUrl }) - Pull image
• dockerHost.createSecret({ name, contentArg, version, labels }) - Create secret
• dockerHost.createService({ name, image, networks, secrets, ports, ... }) - Create service
• dockerHost.activateSwarm() - Initialize swarm mode

Testing

• Tests use Deno's built-in test runner (deno task test)
• Test files in test/ directory
• The first test disables resource/ops sanitization due to signal listeners from smartdaemon

Build

• No build step needed for the TypeScript code
• Binary compilation: deno task compile:all or bash scripts/compile-all.sh
• npm package uses postinstall script to download pre-compiled binaries