@mepuka/skygent 0.2.0

package/src/domain/sync.ts

@@ -0,0 +1,211 @@
+import { Schema } from "effect";
+import * as Monoid from "@effect/typeclass/Monoid";
+import * as Semigroup from "@effect/typeclass/Semigroup";
+import { MonoidSum } from "@effect/typeclass/data/Number";
+import { AuthorFeedFilter } from "./bsky.js";
+import { FilterExprSchema } from "./filter.js";
+import { StoreRef, SyncUpsertPolicy } from "./store.js";
+import { EventSeq, Timestamp } from "./primitives.js";
+
+export const SyncStage = Schema.Literal("source", "parse", "filter", "store");
+export type SyncStage = typeof SyncStage.Type;
+
+export class SyncError extends Schema.TaggedError<SyncError>()("SyncError", {
+  stage: SyncStage,
+  message: Schema.String,
+  cause: Schema.optional(Schema.Unknown)
+}) {}
+
+export class SyncResult extends Schema.Class<SyncResult>("SyncResult")({
+  postsAdded: Schema.Number,
+  postsDeleted: Schema.Number,
+  postsSkipped: Schema.Number,
+  errors: Schema.Array(SyncError)
+}) {}
+
+const SyncResultErrorsMonoid = Monoid.array<SyncError>();
+
+const SyncResultSemigroup: Semigroup.Semigroup<SyncResult> = Semigroup.make(
+  (left, right) =>
+    SyncResult.make({
+      postsAdded: MonoidSum.combine(left.postsAdded, right.postsAdded),
+      postsDeleted: MonoidSum.combine(left.postsDeleted, right.postsDeleted),
+      postsSkipped: MonoidSum.combine(left.postsSkipped, right.postsSkipped),
+      errors: SyncResultErrorsMonoid.combine(left.errors, right.errors)
+    })
+);
+
+export const SyncResultMonoid: Monoid.Monoid<SyncResult> = Monoid.fromSemigroup(
+  SyncResultSemigroup,
+  SyncResult.make({
+    postsAdded: MonoidSum.empty,
+    postsDeleted: MonoidSum.empty,
+    postsSkipped: MonoidSum.empty,
+    errors: SyncResultErrorsMonoid.empty
+  })
+);
+
+export class DataSourceTimeline extends Schema.TaggedClass<DataSourceTimeline>()(
+  "Timeline",
+  {}
+) {}
+
+export class DataSourceFeed extends Schema.TaggedClass<DataSourceFeed>()("Feed", {
+  uri: Schema.String
+}) {}
+
+export class DataSourceList extends Schema.TaggedClass<DataSourceList>()("List", {
+  uri: Schema.String
+}) {}
+
+export class DataSourceNotifications extends Schema.TaggedClass<DataSourceNotifications>()(
+  "Notifications",
+  {}
+) {}
+
+export class DataSourceAuthor extends Schema.TaggedClass<DataSourceAuthor>()("Author", {
+  actor: Schema.String,
+  filter: Schema.optional(AuthorFeedFilter),
+  includePins: Schema.optional(Schema.Boolean)
+}) {}
+
+export class DataSourceThread extends Schema.TaggedClass<DataSourceThread>()("Thread", {
+  uri: Schema.String,
+  depth: Schema.optional(Schema.NonNegativeInt),
+  parentHeight: Schema.optional(Schema.NonNegativeInt)
+}) {}
+
+export class DataSourceJetstream extends Schema.TaggedClass<DataSourceJetstream>()(
+  "Jetstream",
+  {
+    endpoint: Schema.optional(Schema.String),
+    collections: Schema.optional(Schema.Array(Schema.String)),
+    dids: Schema.optional(Schema.Array(Schema.String)),
+    compress: Schema.optional(Schema.Boolean),
+    maxMessageSizeBytes: Schema.optional(Schema.Number)
+  }
+) {}
+
+export const DataSourceSchema = Schema.Union(
+  DataSourceTimeline,
+  DataSourceFeed,
+  DataSourceList,
+  DataSourceNotifications,
+  DataSourceAuthor,
+  DataSourceThread,
+  DataSourceJetstream
+);
+export type DataSource = typeof DataSourceSchema.Type;
+
+export const DataSource = {
+  timeline: (): DataSource => DataSourceTimeline.make({}),
+  feed: (uri: string): DataSource => DataSourceFeed.make({ uri }),
+  list: (uri: string): DataSource => DataSourceList.make({ uri }),
+  notifications: (): DataSource => DataSourceNotifications.make({}),
+  author: (
+    actor: string,
+    options?: {
+      readonly filter?: AuthorFeedFilter;
+      readonly includePins?: boolean;
+    }
+  ): DataSource =>
+    DataSourceAuthor.make({
+      actor,
+      filter: options?.filter,
+      includePins: options?.includePins
+    }),
+  thread: (
+    uri: string,
+    options?: {
+      readonly depth?: number;
+      readonly parentHeight?: number;
+    }
+  ): DataSource =>
+    DataSourceThread.make({
+      uri,
+      depth: options?.depth,
+      parentHeight: options?.parentHeight
+    }),
+  jetstream: (options?: {
+    readonly endpoint?: string;
+    readonly collections?: ReadonlyArray<string>;
+    readonly dids?: ReadonlyArray<string>;
+    readonly compress?: boolean;
+    readonly maxMessageSizeBytes?: number;
+  }): DataSource =>
+    DataSourceJetstream.make({
+      endpoint: options?.endpoint,
+      collections: options?.collections ? [...options.collections] : undefined,
+      dids: options?.dids ? [...options.dids] : undefined,
+      compress: options?.compress,
+      maxMessageSizeBytes: options?.maxMessageSizeBytes
+    })
+};
+
+export class WatchConfig extends Schema.Class<WatchConfig>("WatchConfig")({
+  source: DataSourceSchema,
+  store: StoreRef,
+  filter: FilterExprSchema,
+  interval: Schema.optional(Schema.Duration),
+  policy: Schema.optional(SyncUpsertPolicy)
+}) {}
+
+export class SyncEvent extends Schema.TaggedClass<SyncEvent>()("SyncEvent", {
+  result: SyncResult
+}) {}
+
+export class SyncProgress extends Schema.Class<SyncProgress>("SyncProgress")({
+  processed: Schema.NonNegativeInt,
+  stored: Schema.NonNegativeInt,
+  skipped: Schema.NonNegativeInt,
+  errors: Schema.NonNegativeInt,
+  elapsedMs: Schema.NonNegativeInt,
+  rate: Schema.Number
+}) {}
+
+export class SyncCheckpoint extends Schema.Class<SyncCheckpoint>("SyncCheckpoint")({
+  source: DataSourceSchema,
+  cursor: Schema.optional(Schema.String),
+  lastEventSeq: Schema.optional(EventSeq),
+  filterHash: Schema.optional(Schema.String),
+  updatedAt: Timestamp
+}) {}
+
+export const dataSourceKey = (source: DataSource): string => {
+  const normalizeList = (items: ReadonlyArray<string> | undefined) =>
+    items && items.length > 0 ? [...items].sort().join(",") : "";
+
+  switch (source._tag) {
+    case "Timeline":
+      return "timeline";
+    case "Feed":
+      return `feed:${source.uri}`;
+    case "List":
+      return `list:${source.uri}`;
+    case "Notifications":
+      return "notifications";
+    case "Author": {
+      const filter = source.filter ?? "";
+      const includePins =
+        source.includePins === undefined ? "" : source.includePins ? "1" : "0";
+      return `author:${encodeURIComponent(source.actor)}:${encodeURIComponent(
+        filter
+      )}:${includePins}`;
+    }
+    case "Thread": {
+      const depth = source.depth ?? "";
+      const parentHeight = source.parentHeight ?? "";
+      return `thread:${encodeURIComponent(source.uri)}:${depth}:${parentHeight}`;
+    }
+    case "Jetstream": {
+      const endpoint = source.endpoint ?? "";
+      const collections = normalizeList(source.collections);
+      const dids = normalizeList(source.dids);
+      const compress = source.compress ? "1" : "0";
+      const maxMessageSize = source.maxMessageSizeBytes ?? "";
+      return `jetstream:${encodeURIComponent(endpoint)}:${encodeURIComponent(
+        collections
+      )}:${encodeURIComponent(dids)}:${compress}:${maxMessageSize}`;
+    }
+  }
+};

package/src/domain/text-width.ts

@@ -0,0 +1,56 @@
+const emojiRegex = (() => {
+  try {
+    return new RegExp("\\p{Extended_Pictographic}", "u");
+  } catch {
+    return undefined;
+  }
+})();
+
+const segmenter =
+  typeof Intl !== "undefined" && "Segmenter" in Intl
+    ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+    : undefined;
+
+const toGraphemes = (text: string) =>
+  segmenter
+    ? Array.from(segmenter.segment(text), (part) => part.segment)
+    : Array.from(text);
+
+const isFullwidthCodePoint = (codePoint: number) =>
+  codePoint >= 0x1100 &&
+  (codePoint <= 0x115f ||
+    codePoint === 0x2329 ||
+    codePoint === 0x232a ||
+    (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f) ||
+    (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+    (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+    (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+    (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+    (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+    (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+    (codePoint >= 0x1f300 && codePoint <= 0x1f64f) ||
+    (codePoint >= 0x1f900 && codePoint <= 0x1f9ff) ||
+    (codePoint >= 0x20000 && codePoint <= 0x3fffd));
+
+export const displayWidth = (text: string) => {
+  let width = 0;
+  for (const grapheme of toGraphemes(text)) {
+    if (grapheme.length === 0) {
+      continue;
+    }
+    const codePoint = grapheme.codePointAt(0) ?? 0;
+    const isWide =
+      (emojiRegex ? emojiRegex.test(grapheme) : false) ||
+      isFullwidthCodePoint(codePoint);
+    width += isWide ? 2 : 1;
+  }
+  return width;
+};
+
+export const padEndDisplay = (text: string, targetWidth: number) => {
+  const width = displayWidth(text);
+  if (width >= targetWidth) {
+    return text;
+  }
+  return `${text}${" ".repeat(targetWidth - width)}`;
+};

package/src/services/app-config.ts

@@ -0,0 +1,278 @@
+import { FileSystem } from "@effect/platform";
+import { Path } from "@effect/platform";
+import { Config, Context, Effect, Layer, Option, Schema } from "effect";
+import { formatSchemaError, pickDefined } from "./shared.js";
+import { AppConfig, OutputFormat } from "../domain/config.js";
+import { ConfigError } from "../domain/errors.js";
+
+/**
+ * Application Configuration Service
+ *
+ * This module provides centralized configuration management for the application.
+ * It implements a layered configuration resolution strategy with support for
+ * multiple configuration sources and home directory expansion.
+ *
+ * Configuration Resolution Priority (highest to lowest):
+ * 1. Runtime overrides (ConfigOverrides service)
+ * 2. Environment variables (SKYGENT_*)
+ * 3. Config file (~/.skygent/config.json)
+ * 4. Default values
+ *
+ * Key features:
+ * - Home directory expansion (~ → $HOME)
+ * - Path normalization (relative → absolute)
+ * - Schema validation with detailed error messages
+ * - Graceful handling of missing config files
+ * - Type-safe configuration access via Effect Context
+ *
+ * Environment Variables:
+ * - SKYGENT_SERVICE: Bluesky service URL (default: https://bsky.social)
+ * - SKYGENT_STORE_ROOT: Root directory for store data (default: ~/.skygent)
+ * - SKYGENT_OUTPUT_FORMAT: Output format (json, ndjson, markdown, table)
+ * - SKYGENT_IDENTIFIER: User identifier for authentication
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { AppConfigService, ConfigOverrides } from "./services/app-config.js";
+ *
+ * // Basic usage - read configuration
+ * const program = Effect.gen(function* () {
+ *   const config = yield* AppConfigService;
+ *   console.log(`Store root: ${config.storeRoot}`);
+ *   console.log(`Service: ${config.service}`);
+ * });
+ *
+ * // With runtime overrides
+ * const withOverrides = program.pipe(
+ *   Effect.provide(
+ *     ConfigOverrides.layer({
+ *       storeRoot: "/custom/path",
+ *       outputFormat: "json"
+ *     })
+ *   )
+ * );
+ * ```
+ *
+ * @module services/app-config
+ */
+
+type AppConfigOverrides = Partial<AppConfig>;
+
+/**
+ * Service for providing runtime configuration overrides.
+ *
+ * Allows injection of configuration values at runtime that take precedence
+ * over environment variables and config file settings. This is useful for
+ * CLI arguments, test configuration, or dynamic configuration scenarios.
+ *
+ * @example
+ * ```typescript
+ * // Provide overrides via layer
+ * const overridesLayer = ConfigOverrides.layer({
+ *   storeRoot: "/tmp/test-store",
+ *   outputFormat: "json"
+ * });
+ *
+ * // Use in program
+ * const program = Effect.gen(function* () {
+ *   const config = yield* AppConfigService;
+ *   // config.storeRoot will be "/tmp/test-store"
+ * }).pipe(Effect.provide(overridesLayer));
+ * ```
+ */
+export class ConfigOverrides extends Context.Tag("@skygent/ConfigOverrides")<
+  ConfigOverrides,
+  AppConfigOverrides
+>() {
+  /**
+   * Default empty configuration overrides layer.
+   *
+   * Use this as a base layer when no overrides are needed, or extend it
+   * with custom overrides using Layer.succeed.
+   */
+  static readonly layer = Layer.succeed(ConfigOverrides, {});
+}
+
+const PartialAppConfig = Schema.Struct({
+  service: Schema.optional(Schema.String),
+  storeRoot: Schema.optional(Schema.String),
+  outputFormat: Schema.optional(OutputFormat),
+  identifier: Schema.optional(Schema.String)
+});
+
+type PartialAppConfig = typeof PartialAppConfig.Type;
+
+const defaultService = "https://bsky.social";
+const defaultOutputFormat: OutputFormat = "ndjson";
+const defaultRootDirName = ".skygent";
+const configFileName = "config.json";
+
+
+
+const resolveHomeDir = () =>
+  process.env.HOME ?? process.env.USERPROFILE ?? process.env.HOMEPATH;
+
+const expandHome = (path: Path.Path, value: string, home?: string) => {
+  if (!home) return value;
+  if (value === "~") return home;
+  if (value.startsWith("~/")) {
+    return path.join(home, value.slice(2));
+  }
+  return value;
+};
+
+const resolveDefaultRoot = (path: Path.Path) => {
+  const home = resolveHomeDir();
+  return home ? path.join(home, defaultRootDirName) : path.resolve(defaultRootDirName);
+};
+
+const normalizeStoreRoot = (path: Path.Path, value: string) => {
+  const home = resolveHomeDir();
+  const expanded = expandHome(path, value, home);
+  return path.isAbsolute(expanded) ? expanded : path.resolve(expanded);
+};
+
+const decodeConfigJson = (raw: string, configPath: string) =>
+  Schema.decodeUnknown(Schema.parseJson(PartialAppConfig))(raw).pipe(
+    Effect.mapError((error) =>
+      ConfigError.make({
+        message: `Invalid config JSON at ${configPath}: ${formatSchemaError(error)}`,
+        path: configPath,
+        cause: error
+      })
+    )
+  );
+
+const loadFileConfig = (configPath: string) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const content = yield* fs.readFileString(configPath).pipe(
+      Effect.map(Option.some),
+      Effect.catchTag("SystemError", (error) =>
+        error.reason === "NotFound"
+          ? Effect.succeed(Option.none())
+          : Effect.fail(
+              ConfigError.make({
+                message: `Failed to read config at ${configPath}`,
+                path: configPath,
+                cause: error
+              })
+            )
+      )
+    );
+
+    return yield* Option.match(content, {
+      onNone: () => Effect.succeed({} as PartialAppConfig),
+      onSome: (raw) => decodeConfigJson(raw, configPath)
+    });
+  });
+
+const envOutputFormat = Config.literal("json", "ndjson", "markdown", "table")(
+  "SKYGENT_OUTPUT_FORMAT"
+);
+
+/**
+ * Service for accessing the resolved application configuration.
+ *
+ * Provides type-safe access to the fully resolved application configuration
+ * with values from all sources (overrides, environment, config file, defaults)
+ * merged according to the priority hierarchy.
+ *
+ * @example
+ * ```typescript
+ * // Access configuration in an Effect
+ * const program = Effect.gen(function* () {
+ *   const config = yield* AppConfigService;
+ *
+ *   // All configuration values are resolved and validated
+ *   const { service, storeRoot, outputFormat, identifier } = config;
+ *
+ *   // Use configuration values
+ *   console.log(`Using service: ${service}`);
+ *   console.log(`Storing data in: ${storeRoot}`);
+ * });
+ *
+ * // Provide the configuration layer
+ * const runnable = program.pipe(Effect.provide(AppConfigService.layer));
+ * ```
+ */
+export class AppConfigService extends Context.Tag("@skygent/AppConfig")<
+  AppConfigService,
+  AppConfig
+>() {
+  /**
+   * Layer that constructs the AppConfigService by resolving configuration
+   * from all sources in priority order.
+   *
+   * Resolution order (highest to lowest priority):
+   * 1. ConfigOverrides service values
+   * 2. Environment variables (SKYGENT_*)
+   * 3. ~/.skygent/config.json file
+   * 4. Default values
+   *
+   * @returns Layer providing the resolved AppConfigService
+   * @throws ConfigError if configuration validation fails
+   *
+   * @example
+   * ```typescript
+   * // Basic usage with defaults
+   * const program = Effect.provide(myProgram, AppConfigService.layer);
+   *
+   * // With custom overrides
+   * const customLayer = Layer.merge(
+   *   AppConfigService.layer,
+   *   ConfigOverrides.layer({ outputFormat: "json" })
+   * );
+   * ```
+   */
+  static readonly layer = Layer.effect(
+    AppConfigService,
+    Effect.gen(function* () {
+      const overrides = yield* ConfigOverrides;
+      const path = yield* Path.Path;
+      const defaultRoot = resolveDefaultRoot(path);
+      const configPath = path.join(defaultRoot, configFileName);
+
+      const fileConfig = yield* loadFileConfig(configPath);
+
+      const envService = yield* Config.string("SKYGENT_SERVICE").pipe(Config.option);
+      const envStoreRoot = yield* Config.string("SKYGENT_STORE_ROOT").pipe(Config.option);
+      const envFormat = yield* envOutputFormat.pipe(Config.option);
+      const envIdentifier = yield* Config.string("SKYGENT_IDENTIFIER").pipe(Config.option);
+
+      const envConfig = pickDefined({
+        service: Option.getOrUndefined(envService),
+        storeRoot: Option.getOrUndefined(envStoreRoot),
+        outputFormat: Option.getOrUndefined(envFormat),
+        identifier: Option.getOrUndefined(envIdentifier)
+      });
+
+      const merged = {
+        service: defaultService,
+        storeRoot: defaultRoot,
+        outputFormat: defaultOutputFormat,
+        ...fileConfig,
+        ...envConfig,
+        ...pickDefined(overrides as Record<string, unknown>)
+      };
+
+      const resolvedStoreRoot = merged.storeRoot ?? defaultRoot;
+      const normalized = {
+        ...merged,
+        storeRoot: normalizeStoreRoot(path, resolvedStoreRoot)
+      };
+
+      const decoded = yield* Schema.decodeUnknown(AppConfig)(normalized).pipe(
+        Effect.mapError((error) =>
+          ConfigError.make({
+            message: `Invalid config: ${formatSchemaError(error)}`,
+            path: configPath,
+            cause: error
+          })
+        )
+      );
+      return AppConfigService.of(decoded);
+    })
+  );
+}