feat(cli): add CLI scaffold, app bootstrap, daemon, and shared libraries

Author: alexfreska

.changeset/cli-scaffold-daemon.md

@@ -0,0 +1,5 @@
+---
+cli: minor
+---
+
+Add CLI application with daemon-based architecture, background service scheduling, and core utility libraries.

apps/cli/jest.config.cjs

@@ -0,0 +1,58 @@
+const sharedTransform = {
+  '^.+\\.tsx?$': [
+    'ts-jest',
+    {
+      tsconfig: {
+        target: 'ES2022',
+        module: 'commonjs',
+        moduleResolution: 'node',
+        esModuleInterop: true,
+        strict: true,
+        baseUrl: '.',
+        paths: {
+          '@siastorage/logger': ['../../packages/logger/src/index.ts'],
+          '@siastorage/core/*': ['../../packages/core/src/*'],
+          '@siastorage/node-adapters': ['../../packages/node-adapters/src/index.ts'],
+          '@siastorage/node-adapters/*': ['../../packages/node-adapters/src/*'],
+          '@siastorage/sdk-mock': ['../../packages/sdk-mock/src/index.ts'],
+          '@siafoundation/sia-storage': [
+            '../../node_modules/@siafoundation/sia-storage/dist/index.node.d.ts',
+          ],
+          'bun:sqlite': ['./test/__mocks__/bun-sqlite.ts'],
+        },
+      },
+    },
+  ],
+}
+
+const sharedModuleNameMapper = {
+  '^@siastorage/logger$': '<rootDir>/../../packages/logger/src/index.ts',
+  '^@siastorage/core/(.*)$': '<rootDir>/../../packages/core/src/$1',
+  '^@siastorage/node-adapters$': '<rootDir>/../../packages/node-adapters/src/index.ts',
+  '^@siastorage/node-adapters/(.*)$': '<rootDir>/../../packages/node-adapters/src/$1',
+  '^@siastorage/sdk-mock$': '<rootDir>/../../packages/sdk-mock/src/index.ts',
+  '^@siafoundation/sia-storage$': '<rootDir>/test/__mocks__/@siafoundation/sia-storage.ts',
+  '^bun:sqlite$': '<rootDir>/test/__mocks__/bun-sqlite.ts',
+}
+
+module.exports = {
+  projects: [
+    {
+      displayName: 'unit',
+      testEnvironment: 'node',
+      testMatch: ['<rootDir>/test/**/*.test.ts'],
+      testPathIgnorePatterns: ['<rootDir>/test/e2e/'],
+      transform: sharedTransform,
+      moduleNameMapper: sharedModuleNameMapper,
+    },
+    {
+      displayName: 'e2e',
+      testEnvironment: 'node',
+      maxWorkers: 4,
+      testMatch: ['<rootDir>/test/e2e/**/*.test.ts'],
+      setupFiles: ['<rootDir>/test/e2e/setup.ts'],
+      transform: sharedTransform,
+      moduleNameMapper: sharedModuleNameMapper,
+    },
+  ],
+}

apps/cli/package.json

@@ -1,5 +1,41 @@
 {
   "name": "@siastorage/cli",
-  "version": "0.0.0",
-  "private": true
+  "version": "0.0.1",
+  "private": true,
+  "bin": {
+    "sia": "src/index.ts"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "bun build src/index.ts --compile --outfile dist/sia",
+    "build:linux": "bun build src/index.ts --compile --target=bun-linux-x64 --outfile dist/sia-linux",
+    "link": "bun run build && ln -sf $(pwd)/dist/sia ~/.sia/bin/sia",
+    "lint": "oxlint . && oxfmt --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "jest --selectProjects unit",
+    "test:e2e": "bun run build && jest --selectProjects e2e",
+    "test:all": "bun run build && jest"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.2.0",
+    "@siastorage/core": "workspace:*",
+    "@siastorage/logger": "workspace:*",
+    "@siastorage/node-adapters": "workspace:*",
+    "@siastorage/sdk-mock": "workspace:*",
+    "commander": "14.0.3",
+    "lucide-react": "1.8.0",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "swr": "2.4.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "4.2.2",
+    "@types/node": "22.15.2",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "jest": "29.7.0",
+    "tailwindcss": "4.2.2",
+    "ts-jest": "29.4.6",
+    "typescript": "5.9.3"
+  }
 }

apps/cli/src/app.ts

@@ -0,0 +1,141 @@
+import { uint8ToHex } from '@siastorage/core'
+import type { DatabaseAdapter, SdkAdapter, SdkAuthAdapters } from '@siastorage/core/adapters'
+// oxlint-disable-next-line no-restricted-imports -- CLI daemon needs internal API to set SDK
+import type { AppService, AppServiceInternal } from '@siastorage/core/app'
+import { createAppService } from '@siastorage/core/app'
+import { APP_META } from '@siastorage/core/config'
+import { runMigrations } from '@siastorage/core/db'
+import { coreMigrations, sortMigrations } from '@siastorage/core/db/migrations'
+import type { FsIOAdapter } from '@siastorage/core/services/fsFileUri'
+import type { UploadManager } from '@siastorage/core/services/uploader'
+import {
+  createJsonFileStorage,
+  createNodeCryptoAdapter,
+  createNodeDetectMimeType,
+  createNodeDownloadAdapter,
+  createNodeFsIO,
+  createNodeSdkAdapter,
+  createNodeSdkAuthAdapter,
+  createNodeUploaderAdapters,
+  createSharpThumbnailAdapter,
+  ensureDataDir,
+  getDataDir,
+  getPaths,
+  type NodeSdkAuthResult,
+} from '@siastorage/node-adapters'
+import { createBunDatabase } from '@siastorage/node-adapters/bunDatabase'
+
+export const isTestMode = process.env.SIA_TEST_MODE === '1'
+
+export type CliApp = {
+  service: AppService
+  internal: AppServiceInternal
+  uploadManager: UploadManager
+  db: DatabaseAdapter
+  fsIO: FsIOAdapter
+  paths: ReturnType<typeof getPaths>
+  bootstrap: Bootstrap
+}
+
+export type CreateDatabaseFn = (path: string) => DatabaseAdapter
+
+/**
+ * Bundle of auth + SDK adapters chosen at startup. Holds the strategy for
+ * connecting the SDK so callers don't need to know whether they're running
+ * against a real indexer or a MockSdk.
+ */
+export type Bootstrap = {
+  authAdapters: SdkAuthAdapters
+  sdkAuth: NodeSdkAuthResult
+  /** Set only when running with `SIA_TEST_MODE=1` — pre-attached during bootstrap. */
+  testSdkAdapter?: SdkAdapter
+  /** Performs the SDK connection (real handshake or test-mode short-circuit). */
+  connect: (app: CliApp) => Promise<boolean>
+}
+
+async function buildBootstrap(): Promise<Bootstrap> {
+  if (isTestMode) {
+    const { createTestBootstrap } = await import('./testMode')
+    return createTestBootstrap()
+  }
+  return createRealBootstrap()
+}
+
+function createRealBootstrap(): Bootstrap {
+  const sdkAuth = createNodeSdkAuthAdapter()
+  return {
+    authAdapters: sdkAuth.adapters,
+    sdkAuth,
+    async connect(app) {
+      const indexerURL = await app.service.settings.getIndexerURL()
+      const keyBytes = await app.service.auth.getAppKey(indexerURL)
+      if (!keyBytes) return false
+
+      const keyHex = uint8ToHex(new Uint8Array(keyBytes))
+      await sdkAuth.adapters.createBuilder(indexerURL, JSON.stringify(APP_META))
+
+      const connected = await sdkAuth.adapters.connectWithKey(keyHex)
+      if (!connected) return false
+
+      const sdk = sdkAuth.getLastSdk()
+      if (!sdk) return false
+
+      app.internal.setSdk(createNodeSdkAdapter(sdk))
+      app.service.connection.setState({ isConnected: true })
+      app.internal.initUploader()
+      return true
+    },
+  }
+}
+
+export async function createCliAppService(
+  dataDir?: string,
+  opts?: { createDatabase?: CreateDatabaseFn },
+): Promise<CliApp> {
+  const dir = dataDir ?? getDataDir()
+  const p = getPaths(dir)
+  ensureDataDir(dir)
+
+  const createDb = opts?.createDatabase ?? createBunDatabase
+  const db = createDb(p.dbPath)
+  await runMigrations(db, sortMigrations(coreMigrations))
+
+  const storage = createJsonFileStorage(p.storagePath)
+  const secrets = createJsonFileStorage(p.secretsPath, { mode: 0o600 })
+  const crypto = createNodeCryptoAdapter()
+  const fsIO = createNodeFsIO(p.filesDir)
+  const uploaderAdapters = createNodeUploaderAdapters()
+  const detectMimeType = createNodeDetectMimeType()
+  const thumbnail = createSharpThumbnailAdapter()
+
+  const bootstrap = await buildBootstrap()
+
+  const { service, internal, uploadManager } = createAppService({
+    db,
+    storage,
+    secrets,
+    crypto,
+    fsIO,
+    downloadObject: createNodeDownloadAdapter({
+      fsIO,
+      getAppKey: async (indexerURL: string) => service.auth.getAppKey(indexerURL),
+    }),
+    uploader: uploaderAdapters,
+    sdkAuth: bootstrap.authAdapters,
+    thumbnail,
+    detectMimeType,
+  })
+
+  // In test mode the MockSdk attaches before connectSdk runs, so the daemon
+  // comes up with an SDK already wired and connectSdk just flips the flag.
+  if (bootstrap.testSdkAdapter) {
+    internal.setSdk(bootstrap.testSdkAdapter)
+  }
+
+  return { service, internal, uploadManager, db, fsIO, paths: p, bootstrap }
+}
+
+/** Performs the SDK connection chosen at bootstrap (real or test-mode). */
+export function connectSdk(app: CliApp): Promise<boolean> {
+  return app.bootstrap.connect(app)
+}

apps/cli/src/daemon/entry.ts

@@ -0,0 +1,62 @@
+import { logger } from '@siastorage/logger'
+import { writeState } from '@siastorage/node-adapters'
+import { connectSdk, createCliAppService } from '../app'
+import { startIpcDispatcher } from './ipc'
+import {
+  acquireLockOrExit,
+  attachSignalHandlers,
+  executeShutdown,
+  type ShutdownContext,
+} from './lifecycle'
+import { initializeScheduler } from './scheduler'
+
+export type DaemonContext = ShutdownContext & {
+  connected: boolean
+  shutdown: () => Promise<void>
+}
+
+/**
+ * Boots the daemon end-to-end: app service, single-instance lock, SDK
+ * connection, scheduled background services, IPC server, signal handlers.
+ * Shared by both `sia daemon start` and `sia serve`; the latter wraps the
+ * returned context with an HTTP server.
+ */
+export async function startServices(dataDir?: string): Promise<DaemonContext> {
+  const app = await createCliAppService(dataDir)
+  const lock = acquireLockOrExit(app.paths)
+
+  let connected = false
+  try {
+    connected = await connectSdk(app)
+  } catch (e) {
+    logger.warn('daemon', 'sdk_connect_failed', { error: e as Error })
+  }
+
+  const { scheduler } = initializeScheduler(app)
+
+  writeState(app.paths.statePath, {
+    pid: process.pid,
+    startedAt: Date.now(),
+    connected,
+  })
+
+  // The IPC server's `shutdown` handler needs to call back into the shutdown
+  // function — but the function references the IPC server itself. Resolve by
+  // declaring `ctx` first and assigning after both are constructed.
+  let ctx: ShutdownContext
+  const shutdown = () => executeShutdown(ctx)
+  const ipcServer = startIpcDispatcher(app, app.paths.sockPath, () => {
+    void shutdown()
+  })
+  ctx = { app, scheduler, ipcServer, lock }
+
+  attachSignalHandlers(shutdown)
+
+  return { ...ctx, connected, shutdown }
+}
+
+export async function startDaemon(dataDir?: string): Promise<void> {
+  const ctx = await startServices(dataDir)
+  logger.info('daemon', 'started', { pid: process.pid, connected: ctx.connected })
+  console.log(`Daemon started (PID: ${process.pid})`)
+}

apps/cli/src/daemon/ipc/index.ts

@@ -0,0 +1,45 @@
+import { registerAppServiceIpc } from '@siastorage/core/app'
+import { startIpcServer } from '@siastorage/node-adapters'
+import type { CliApp } from '../../app'
+import { registerStatusHandlers } from './status'
+import { registerUploadHandlers } from './upload'
+
+export type IpcHandler = (params: Record<string, unknown>) => Promise<unknown>
+export type IpcHandlerMap = Map<string, IpcHandler>
+
+/**
+ * Wires the daemon's IPC server. Custom handlers (`ping`, `status`, `upload`,
+ * `uploadState`, `shutdown`) are registered explicitly; the AppService facade
+ * is reflected onto `ds:<namespace>:<method>` channels via
+ * `registerAppServiceIpc`. Both flow through the same handler map. Feature
+ * branches (e.g. `cli/watch`) extend the handler map by registering their own
+ * custom handlers in this same way.
+ */
+export function startIpcDispatcher(
+  app: CliApp,
+  sockPath: string,
+  onShutdown: () => void,
+): ReturnType<typeof startIpcServer> {
+  const handlers: IpcHandlerMap = new Map()
+
+  registerStatusHandlers(handlers, app, onShutdown)
+  registerUploadHandlers(handlers, app)
+
+  registerAppServiceIpc(
+    {
+      handle: (channel, handler) => {
+        handlers.set(channel, async (params) => {
+          const args = (params as { args?: unknown[] })?.args ?? []
+          return handler(null, ...args)
+        })
+      },
+    },
+    app.service,
+  )
+
+  return startIpcServer(sockPath, async (method, params) => {
+    const handler = handlers.get(method)
+    if (!handler) throw new Error(`Unknown method: ${method}`)
+    return handler(params)
+  })
+}

apps/cli/src/daemon/ipc/status.ts

@@ -0,0 +1,22 @@
+import type { CliApp } from '../../app'
+import type { IpcHandlerMap } from './index'
+
+/** Handlers for daemon-process-level queries (not app state). */
+export function registerStatusHandlers(
+  handlers: IpcHandlerMap,
+  app: CliApp,
+  onShutdown: () => void,
+): void {
+  handlers.set('ping', async () => ({ ok: true }))
+
+  handlers.set('status', async () => ({
+    running: true,
+    pid: process.pid,
+    connected: app.service.connection.getState().isConnected,
+  }))
+
+  handlers.set('shutdown', async () => {
+    onShutdown()
+    return { ok: true }
+  })
+}