@atomservice/core 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@atomservice/core",
+  "version": "0.1.0",
+  "description": "atomservice 编排核心：defineService、依赖拓扑、生命周期与 CLI 运行时",
+  "type": "module",
+  "author": "openorson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openorson/atomservice.git",
+    "directory": "packages/core"
+  },
+  "bugs": "https://github.com/openorson/atomservice/issues",
+  "homepage": "https://github.com/openorson/atomservice/tree/main/packages/core#readme",
+  "keywords": [
+    "atomservice",
+    "self-hosted",
+    "podman",
+    "orchestration",
+    "bun"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "consola": "^3.4.2",
+    "defu": "^6.1.7",
+    "pathe": "^2.0.3",
+    "picocolors": "^1.1.1",
+    "zod": "^4.4.3"
+  }
+}

package/src/core.config.ts

@@ -0,0 +1,26 @@
+import fs from "node:fs"
+import { z } from "zod"
+import { ATOMSERVICE_DIR, CONFIG_PATH } from "./core.consts.ts"
+import { UserError } from "./core.errors.ts"
+import type { ResolvedAtomserviceConfig } from "./core.types.ts"
+
+const UserConfigSchema = z.object({
+  root: z.string().optional(),
+  services: z.array(z.any()),
+})
+
+export async function loadConfig(): Promise<ResolvedAtomserviceConfig> {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    throw new UserError(`找不到配置文件 ${CONFIG_PATH}`, "请先执行 atom init 创建配置文件")
+  }
+  const configPath = CONFIG_PATH
+  const mod = await import(configPath)
+  const raw = mod.default ?? mod
+
+  const parsed = UserConfigSchema.parse(raw)
+
+  return {
+    root: parsed.root ?? ATOMSERVICE_DIR,
+    services: parsed.services,
+  }
+}

package/src/core.consts.ts

@@ -0,0 +1,10 @@
+import os from "node:os"
+import path from "node:path"
+
+export const ATOMSERVICE_DIR = path.join(os.homedir(), ".atomservice")
+export const CONFIG_PATH = path.join(ATOMSERVICE_DIR, "atom.config.ts")
+
+export const YELLOW = Bun.color("#facc15", "ansi") ?? ""
+export const RESET = "\x1b[0m"
+export const BOLD = "\x1b[1m"
+export const DIM = "\x1b[2m"

package/src/core.define.ts

@@ -0,0 +1,27 @@
+import { useService } from "./core.hooks.ts"
+import type { AtomserviceConfig, CallableService, ServiceDefinition } from "./core.types.ts"
+
+function makeCallable<ServiceInstance>(def: ServiceDefinition<ServiceInstance>): CallableService<ServiceInstance> {
+  const callable = (): ServiceInstance => useService(def as ServiceDefinition<ServiceInstance>)
+  const { name, ...rest } = def
+  Object.assign(callable, rest)
+  Object.defineProperty(callable, "name", { value: name, configurable: true })
+  return callable as CallableService<ServiceInstance>
+}
+
+export function defineService<ServiceInstance = void>({
+  name,
+  id = "default",
+  setup,
+}: {
+  name: string
+  id?: string
+  setup: () => Bun.MaybePromise<ServiceInstance>
+}): CallableService<ServiceInstance> {
+  const def: ServiceDefinition<ServiceInstance> = { name, id, _setup: setup }
+  return makeCallable(def)
+}
+
+export function defineConfig(config: AtomserviceConfig): AtomserviceConfig {
+  return config
+}

package/src/core.errors.ts

@@ -0,0 +1,15 @@
+/**
+ * 用户可见错误
+ *
+ * - 用于表示「可预期、由用户配置或环境导致」的错误
+ * - CLI 捕获后只打印简洁的中文提示，不输出堆栈
+ */
+export class UserError extends Error {
+  readonly hint?: string
+
+  constructor(message: string, hint?: string) {
+    super(message)
+    this.name = "UserError"
+    this.hint = hint
+  }
+}

package/src/core.hooks.ts

@@ -0,0 +1,267 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+import { readFileSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import * as clack from "@clack/prompts"
+import { BOLD, DIM, RESET, YELLOW } from "./core.consts.ts"
+import { UserError } from "./core.errors.ts"
+import type {
+  AnyService,
+  HealthStatus,
+  Logger,
+  ResolvedAtomserviceConfig,
+  ServiceCommand,
+  ServiceDefinition,
+  ServiceLifecycle,
+  ServiceStateHandle,
+  ServiceStateWatchRule,
+  SetupStore,
+} from "./core.types.ts"
+
+const setupStore = new AsyncLocalStorage<SetupStore>()
+const apiRegistry = new Map<string, unknown>()
+function getStore(hookName: string): SetupStore {
+  const store = setupStore.getStore()
+  if (!store) throw new Error(`${hookName}() 必须在 defineService 的 setup 内调用`)
+  return store
+}
+
+export function onUp(fn: () => Bun.MaybePromise<void>): void {
+  getStore("onUp").lifecycle.upHandlers.push(fn)
+}
+
+export function onDown(fn: () => Bun.MaybePromise<void>): void {
+  getStore("onDown").lifecycle.downHandlers.push(fn)
+}
+
+export function onHealth(fn: () => Bun.MaybePromise<HealthStatus>): void {
+  getStore("onHealth").lifecycle.healthHandler = fn
+}
+
+export function addCommand(cmd: ServiceCommand): void {
+  getStore("addCommand").lifecycle.commands.push(cmd)
+}
+
+export function useLogger(): Logger {
+  return getStore("useLogger").logger
+}
+
+export function useShell(): typeof Bun.$ {
+  const shell = getStore("useShell").$
+  const RESET = "\x1b[0m"
+  const BAR = Bun.color("#52525b", "ansi") ?? ""
+  const CMD = Bun.color("#a1a1aa", "ansi") ?? ""
+  const OUT = Bun.color("#71717a", "ansi") ?? ""
+  const home = os.homedir()
+  const short = (s: string) => s.replaceAll(home, "~")
+
+  function run(...args: Parameters<typeof Bun.$>) {
+    // 默认抛错（沿用 Bun.$ 行为），服务通过 .nothrow() 显式忽略；.quiet() 抑制实时输出
+    if (!process.env.ATOMSERVICE_VERBOSE) return Reflect.apply(shell, undefined, args).quiet()
+
+    // verbose 模式：内部以 nothrow 捕获结果用于打印，再按需重新抛错
+    const cmd = Reflect.apply(shell, undefined, args).quiet().nothrow()
+    const strings = args[0] as TemplateStringsArray
+    const values = args.slice(1)
+    const cmdStr = strings.reduce(
+      (acc, str, i) =>
+        acc +
+        str +
+        (i < values.length ? (Array.isArray(values[i]) ? (values[i] as unknown[]).join(" ") : String(values[i])) : ""),
+      "",
+    )
+
+    // 惰性执行：仅在首次 await 时运行一次，throwOnError 由是否调用过 .nothrow() 决定
+    let throwOnError = true
+    let started: Promise<Bun.ShellOutput> | undefined
+    const exec = () => {
+      if (started) return started
+      started = (async () => {
+        process.stdout.write(`${BAR}│${RESET}  ${CMD}$ ${short(cmdStr)}${RESET}\n`)
+        const result = await cmd
+        const printLines = (buf: Buffer | undefined) => {
+          for (const line of (buf?.toString() ?? "").split("\n")) {
+            const trimmed = line.trim()
+            if (!trimmed) continue
+            // 过滤 podman-compose 透传的 provider 提示噪音
+            if (trimmed.includes("Executing external compose provider")) continue
+            process.stdout.write(`${BAR}│${RESET}    ${OUT}${short(line.trimEnd())}${RESET}\n`)
+          }
+        }
+        printLines(result.stdout)
+        printLines(result.stderr)
+        if (throwOnError && result.exitCode !== 0) {
+          throw new Error(result.stderr?.toString().trim() || `Exit code ${result.exitCode}`)
+        }
+        return result
+      })()
+      return started
+    }
+
+    const handle = {
+      quiet: () => handle,
+      nothrow: () => {
+        throwOnError = false
+        return handle
+      },
+      // biome-ignore lint/suspicious/noThenProperty: 实现 thenable 以在 verbose 模式拦截并打印 shell 输出
+      then: (onFulfilled?: (r: Bun.ShellOutput) => unknown, onRejected?: (e: unknown) => unknown) =>
+        exec().then(onFulfilled, onRejected),
+      catch: (onRejected?: (e: unknown) => unknown) => exec().catch(onRejected),
+      finally: (onFinally?: () => void) => exec().finally(onFinally),
+      text: () => exec().then((r) => r.text()),
+      blob: () => exec().then((r) => r.blob()),
+      json: () => exec().then((r) => r.json()),
+      arrayBuffer: () => exec().then((r) => r.arrayBuffer()),
+    }
+    return handle
+  }
+
+  return new Proxy(shell, {
+    apply(_target, _thisArg, args) {
+      return run(...(args as Parameters<typeof Bun.$>))
+    },
+  })
+}
+
+export function useConfig(): ResolvedAtomserviceConfig {
+  return getStore("useConfig").config
+}
+
+export function useService<ServiceInstance>(service: ServiceDefinition<ServiceInstance>): ServiceInstance {
+  const store = getStore("useService")
+  const id = resolveServiceId(service)
+  store.lifecycle.deps.add(id)
+  return new Proxy({} as Record<string, unknown>, {
+    get(_, prop: string) {
+      const api = apiRegistry.get(id) as Record<string, unknown> | undefined
+      if (!api) throw new Error(`服务 "${id}" 未暴露 API，或尚未完成初始化`)
+      const val = api[prop]
+      if (typeof val === "function") {
+        return (...args: unknown[]) => (val as (...a: unknown[]) => unknown)(...args)
+      }
+      return val
+    },
+  }) as unknown as ServiceInstance
+}
+
+export function resolveServiceId(service: Pick<AnyService, "name" | "id">): string {
+  return service.id !== "default" && service.id ? `${service.name}:${service.id}` : service.name
+}
+
+export async function runSetup(
+  service: AnyService,
+  config: ResolvedAtomserviceConfig,
+  logger: Logger,
+): Promise<ServiceLifecycle> {
+  const lifecycle: ServiceLifecycle = {
+    upHandlers: [],
+    downHandlers: [],
+    commands: [],
+    deps: new Set(),
+  }
+  const store: SetupStore = { lifecycle, config, logger, $: Bun.$, name: service.name, id: service.id }
+  const api = await setupStore.run(store, () => service._setup())
+  if (api != null) {
+    apiRegistry.set(resolveServiceId(service), api)
+  }
+  return lifecycle
+}
+
+export function _clearApiRegistry(): void {
+  apiRegistry.clear()
+}
+
+function printStateChangeWarning(
+  key: string,
+  risk: "low" | "high",
+  previousValue: unknown,
+  currentValue: unknown,
+  message: string,
+): void {
+  const riskLabel = risk === "high" ? ` ${BOLD}[高风险]${RESET}${YELLOW}` : ""
+  process.stdout.write(
+    `${YELLOW}${BOLD}⚠ 配置变更检测 [${key}]${riskLabel}${RESET}\n` +
+      `${DIM}  上次值  ${RESET}${String(previousValue ?? "(未设置)")}\n` +
+      `${DIM}  当前值  ${RESET}${String(currentValue ?? "(未设置)")}\n` +
+      `${DIM}  说明    ${RESET}${message}\n`,
+  )
+}
+
+async function askConfirmation(key: string): Promise<boolean> {
+  if (process.argv.includes("--yes")) return true
+  if (!process.stdout.isTTY) {
+    process.stdout.write(
+      `${YELLOW}  [${key}] 非交互环境，高风险变更已自动中止。如需强制继续，添加 --yes 参数。${RESET}\n`,
+    )
+    return false
+  }
+  const result = await clack.confirm({ message: `确认继续启动?` })
+  if (clack.isCancel(result)) {
+    clack.cancel("已取消")
+    return false
+  }
+  return result
+}
+
+export function useState<TState extends Record<string, unknown>>(): ServiceStateHandle<TState> {
+  const store = getStore("useState")
+  const { config } = store
+
+  const dirName = store.id !== "default" && store.id ? `${store.name}-${store.id}` : store.name
+  const stateFilePath = path.join(config.root, dirName, "atomservice.state.json")
+
+  let prev: TState | null = null
+  try {
+    const content = readFileSync(stateFilePath, "utf-8")
+    prev = JSON.parse(content) as TState
+  } catch {
+    prev = null
+  }
+
+  const watchRules: Array<{ key: string; rule: ServiceStateWatchRule<TState, unknown> }> = []
+
+  return {
+    prev,
+
+    watch(key: string, rule: ServiceStateWatchRule<TState, unknown>) {
+      watchRules.push({ key, rule })
+    },
+
+    async checkChanges(currentState: TState) {
+      if (!prev) return
+
+      for (const { key, rule } of watchRules) {
+        const select = rule.select ?? ((s: TState) => s[key as keyof TState] as unknown)
+        const previousValue = select(prev)
+        const currentValue = select(currentState)
+
+        let message: string | undefined
+
+        if (previousValue == null && currentValue != null && rule.added) {
+          message = rule.added(currentValue)
+        } else if (previousValue != null && currentValue == null && rule.removed) {
+          message = rule.removed(previousValue)
+        } else if (previousValue !== currentValue && previousValue != null && currentValue != null && rule.changed) {
+          message = rule.changed(previousValue, currentValue)
+        }
+
+        if (!message) continue
+
+        const risk = rule.risk ?? "low"
+        printStateChangeWarning(key, risk, previousValue, currentValue, message)
+
+        if (risk === "high") {
+          const confirmed = await askConfirmation(key)
+          if (!confirmed) {
+            throw new UserError(`[${key}] 高风险变更未确认，启动已中止`)
+          }
+        }
+      }
+    },
+
+    async save(currentState: TState) {
+      await Bun.write(stateFilePath, JSON.stringify(currentState, null, 2))
+    },
+  } as ServiceStateHandle<TState>
+}

package/src/core.logger.ts

@@ -0,0 +1,12 @@
+import type { Logger } from "./core.types.ts"
+
+export function createLogger(tag?: string): Logger {
+  const prefix = tag ? `[${tag}]` : ""
+  return {
+    info: (msg) => console.log(`${prefix} ${msg}`),
+    warn: (msg) => console.warn(`${prefix} ${msg}`),
+    error: (msg) => console.error(`${prefix} ${msg}`),
+    debug: (msg) => console.debug(`${prefix} ${msg}`),
+    success: (msg) => console.log(`${prefix} ${msg}`),
+  }
+}

package/src/core.runner.ts

@@ -0,0 +1,79 @@
+import { resolveServiceId, runSetup } from "./core.hooks.ts"
+import { createLogger } from "./core.logger.ts"
+import { topoSort } from "./core.topo.ts"
+import type { HealthStatus, InitResult, Logger, ResolvedAtomserviceConfig, ServiceLifecycle } from "./core.types.ts"
+
+async function initServices(config: ResolvedAtomserviceConfig): Promise<{ sorted: InitResult[] }> {
+  const results: InitResult[] = []
+  const lifecycleMap = new Map<string, ServiceLifecycle>()
+
+  for (const service of config.services) {
+    const id = resolveServiceId(service)
+    const logger = createLogger(id)
+    const lifecycle = await runSetup(service, config, logger)
+    lifecycleMap.set(id, lifecycle)
+    results.push({ serviceId: id, lifecycle, logger })
+  }
+
+  const sortedServices = topoSort(config.services, lifecycleMap)
+  const idToResult = new Map<string, InitResult>()
+  for (const r of results) {
+    idToResult.set(r.serviceId, r)
+  }
+
+  const sorted = sortedServices.map((s) => {
+    const id = resolveServiceId(s)
+    const r = idToResult.get(id)
+    if (!r) throw new Error(`内部错误：找不到服务 "${id}" 的初始化结果`)
+    return r
+  })
+
+  return { sorted }
+}
+
+export async function runUp(config: ResolvedAtomserviceConfig): Promise<void> {
+  const { sorted } = await initServices(config)
+  for (const { lifecycle } of sorted) {
+    for (const fn of lifecycle.upHandlers) {
+      await fn()
+    }
+  }
+}
+
+export async function runDown(config: ResolvedAtomserviceConfig): Promise<void> {
+  const { sorted } = await initServices(config)
+  for (const { lifecycle } of [...sorted].reverse()) {
+    for (const fn of lifecycle.downHandlers) {
+      await fn()
+    }
+  }
+}
+
+export async function runStatus(config: ResolvedAtomserviceConfig): Promise<Map<string, HealthStatus>> {
+  const { sorted } = await initServices(config)
+  const results = new Map<string, HealthStatus>()
+
+  await Promise.all(
+    sorted.map(async ({ serviceId, lifecycle }) => {
+      const status = lifecycle.healthHandler ? await lifecycle.healthHandler() : ({ status: "unknown" } as const)
+      results.set(serviceId, status)
+    }),
+  )
+
+  return results
+}
+
+export async function initForCli(config: ResolvedAtomserviceConfig): Promise<
+  Array<{
+    serviceId: string
+    state: ServiceLifecycle
+    logger: Logger
+  }>
+> {
+  const { sorted } = await initServices(config)
+  return sorted.map(({ serviceId, lifecycle, logger }) => ({
+    serviceId,
+    state: lifecycle,
+    logger,
+  }))
+}

package/src/core.tmpl.ts

@@ -0,0 +1,6 @@
+import type { Primitive } from "./core.types.ts"
+
+export function tmpl(strings: TemplateStringsArray, ...values: Primitive[]): string {
+  const result = strings.raw.reduce((acc, str, i) => `${acc}${str}${values[i] ?? ""}`, "")
+  return result.replace(/^\\\n/, "")
+}

package/src/core.topo.ts

@@ -0,0 +1,141 @@
+import { UserError } from "./core.errors.ts"
+import { resolveServiceId } from "./core.hooks.ts"
+import type { AnyService, ServiceLifecycle } from "./core.types.ts"
+
+export function topoSort(services: AnyService[], stateMap: Map<string, ServiceLifecycle>): AnyService[] {
+  const idToService = new Map<string, AnyService>()
+  for (const a of services) {
+    idToService.set(resolveServiceId(a), a)
+  }
+
+  const byName = new Map<string, string[]>()
+  for (const id of idToService.keys()) {
+    const name = id.split(":")[0] ?? id
+    const list = byName.get(name) ?? []
+    list.push(id)
+    byName.set(name, list)
+  }
+
+  function resolveDepIds(dep: string): string[] {
+    if (idToService.has(dep)) return [dep]
+    return byName.get(dep) ?? []
+  }
+
+  const inDegree = new Map<string, number>()
+  const edges = new Map<string, string[]>() // from → dependants
+
+  for (const id of idToService.keys()) {
+    inDegree.set(id, 0)
+    edges.set(id, [])
+  }
+
+  for (const [id, state] of stateMap) {
+    for (const dep of state.deps) {
+      const depIds = resolveDepIds(dep)
+      if (depIds.length === 0) {
+        throw new UserError(`服务 "${id}" 声明了不存在的依赖 "${dep}"`)
+      }
+      for (const depId of depIds) {
+        edges.get(depId)?.push(id)
+        inDegree.set(id, (inDegree.get(id) ?? 0) + 1)
+      }
+    }
+  }
+
+  const queue: string[] = []
+  for (const [id, deg] of inDegree) {
+    if (deg === 0) queue.push(id)
+  }
+
+  const sorted: AnyService[] = []
+  while (queue.length > 0) {
+    const id = queue.shift()
+    if (id === undefined) break
+    const service = idToService.get(id)
+    if (service) sorted.push(service)
+    for (const dependant of edges.get(id) ?? []) {
+      const newDeg = (inDegree.get(dependant) ?? 0) - 1
+      inDegree.set(dependant, newDeg)
+      if (newDeg === 0) queue.push(dependant)
+    }
+  }
+
+  if (sorted.length !== services.length) {
+    throw new UserError("服务依赖存在循环，无法完成拓扑排序")
+  }
+
+  return sorted
+}
+
+/**
+ * 根据用户指定的服务名筛选要操作的服务子集
+ *
+ * - `direction: "deps"` — 含目标服务及其全部传递依赖（用于 up）
+ * - `direction: "dependents"` — 含目标服务及其全部传递下游（用于 down）
+ * - `only: true` — 仅目标服务本身，不做依赖联动
+ *
+ * 返回结果保持传入 `results` 的相对顺序
+ */
+export function selectServices<Result extends { serviceId: string; state: ServiceLifecycle }>(
+  results: Result[],
+  names: string[],
+  opts: { direction: "deps" | "dependents"; only: boolean },
+): Result[] {
+  const ids = results.map((r) => r.serviceId)
+  const idSet = new Set(ids)
+
+  const byName = new Map<string, string[]>()
+  for (const id of ids) {
+    const name = id.split(":")[0] ?? id
+    const list = byName.get(name) ?? []
+    list.push(id)
+    byName.set(name, list)
+  }
+
+  const targets = new Set<string>()
+  for (const raw of names) {
+    if (idSet.has(raw)) {
+      targets.add(raw)
+      continue
+    }
+    const matched = byName.get(raw)
+    if (!matched || matched.length === 0) {
+      throw new UserError(`找不到服务 "${raw}"`, `已配置的服务：${ids.join("、") || "（无）"}`)
+    }
+    for (const id of matched) targets.add(id)
+  }
+
+  if (opts.only) {
+    return results.filter((r) => targets.has(r.serviceId))
+  }
+
+  const depsMap = new Map<string, Set<string>>()
+  const dependentsMap = new Map<string, Set<string>>()
+  for (const id of ids) {
+    depsMap.set(id, new Set())
+    dependentsMap.set(id, new Set())
+  }
+  for (const r of results) {
+    for (const dep of r.state.deps) {
+      const depIds = idSet.has(dep) ? [dep] : (byName.get(dep) ?? [])
+      for (const depId of depIds) {
+        depsMap.get(r.serviceId)?.add(depId)
+        dependentsMap.get(depId)?.add(r.serviceId)
+      }
+    }
+  }
+
+  const graph = opts.direction === "deps" ? depsMap : dependentsMap
+  const selected = new Set<string>()
+  const stack = [...targets]
+  while (stack.length > 0) {
+    const id = stack.pop()
+    if (id === undefined || selected.has(id)) continue
+    selected.add(id)
+    for (const next of graph.get(id) ?? []) {
+      if (!selected.has(next)) stack.push(next)
+    }
+  }
+
+  return results.filter((r) => selected.has(r.serviceId))
+}

package/src/core.types.ts

@@ -0,0 +1,81 @@
+export interface Logger {
+  info(msg: string): void
+  warn(msg: string): void
+  error(msg: string): void
+  debug(msg: string): void
+  success(msg: string): void
+}
+
+export type HealthStatus =
+  | { status: "healthy"; message?: string }
+  | { status: "unhealthy"; message: string }
+  | { status: "unknown"; message?: string }
+
+export interface ResolvedAtomserviceConfig {
+  root: string
+  services: AnyService[]
+}
+
+export interface AtomserviceConfig {
+  root?: string
+  services: AnyService[]
+}
+
+export interface ServiceDefinition<ServiceInstance = void> {
+  readonly name: string
+  readonly id: string
+  readonly _setup: () => Bun.MaybePromise<ServiceInstance>
+}
+
+export type AnyService = ServiceDefinition<unknown>
+
+export interface ServiceCommand {
+  name: string
+  description: string
+  handler(args: Record<string, string>): Bun.MaybePromise<void>
+}
+
+export interface ServiceLifecycle {
+  upHandlers: Array<() => Bun.MaybePromise<void>>
+  downHandlers: Array<() => Bun.MaybePromise<void>>
+  healthHandler?: () => Bun.MaybePromise<HealthStatus>
+  commands: ServiceCommand[]
+  deps: Set<string>
+}
+
+export type ServiceStateWatchRisk = "low" | "high"
+
+export interface ServiceStateWatchRule<TState, TValue> {
+  select?: (state: TState) => TValue
+  risk?: ServiceStateWatchRisk
+  added?: (currentValue: TValue) => string
+  removed?: (previousValue: TValue) => string
+  changed?: (previousValue: TValue, currentValue: TValue) => string
+}
+
+export interface ServiceStateHandle<TState extends Record<string, unknown>> {
+  readonly prev: TState | null
+  watch<TKey extends keyof TState & string>(key: TKey, rule: ServiceStateWatchRule<TState, TState[TKey]>): void
+  watch<TValue>(key: string, rule: ServiceStateWatchRule<TState, TValue> & { select: (state: TState) => TValue }): void
+  checkChanges(currentState: TState): Promise<void>
+  save(currentState: TState): Promise<void>
+}
+
+export type Primitive = string | number | boolean
+
+export interface InitResult {
+  serviceId: string
+  lifecycle: ServiceLifecycle
+  logger: Logger
+}
+
+export interface SetupStore {
+  lifecycle: ServiceLifecycle
+  config: ResolvedAtomserviceConfig
+  logger: Logger
+  $: typeof Bun.$
+  name: string
+  id: string
+}
+
+export type CallableService<ServiceInstance = void> = ServiceDefinition<ServiceInstance> & (() => ServiceInstance)

package/src/index.ts

@@ -0,0 +1,35 @@
+export { loadConfig } from "./core.config.ts"
+export { ATOMSERVICE_DIR } from "./core.consts.ts"
+export { defineConfig, defineService } from "./core.define.ts"
+export { UserError } from "./core.errors.ts"
+export {
+  addCommand,
+  onDown,
+  onHealth,
+  onUp,
+  resolveServiceId,
+  useConfig,
+  useLogger,
+  useService,
+  useShell,
+  useState,
+} from "./core.hooks.ts"
+export { createLogger } from "./core.logger.ts"
+export { initForCli, runDown, runStatus, runUp } from "./core.runner.ts"
+export { tmpl } from "./core.tmpl.ts"
+export { selectServices, topoSort } from "./core.topo.ts"
+export type {
+  AnyService,
+  AtomserviceConfig,
+  CallableService,
+  HealthStatus,
+  InitResult,
+  Logger,
+  ResolvedAtomserviceConfig,
+  ServiceCommand,
+  ServiceDefinition,
+  ServiceLifecycle,
+  ServiceStateHandle,
+  ServiceStateWatchRisk,
+  ServiceStateWatchRule,
+} from "./core.types.ts"