@mepuka/skygent 0.2.0

package/src/cli/range.ts

@@ -0,0 +1,44 @@
+import { Effect, Schema } from "effect";
+import { Timestamp } from "../domain/primitives.js";
+import { CliInputError } from "./errors.js";
+
+const rangeExample = "2026-01-01T00:00:00Z..2026-01-31T23:59:59Z";
+
+const parseTimestamp = (value: string) =>
+  Schema.decodeUnknown(Timestamp)(value).pipe(
+    Effect.mapError((cause) =>
+      CliInputError.make({
+        message:
+          `Invalid timestamp "${value}". Expected ISO 8601 with timezone ` +
+          `(e.g. 2026-01-01T00:00:00Z).`,
+        cause
+      })
+    )
+  );
+
+export const parseRange = (raw: string) =>
+  Effect.gen(function* () {
+    const [startRaw = "", endRaw = ""] = raw.split("..");
+    if (startRaw.length === 0 || endRaw.length === 0) {
+      return yield* CliInputError.make({
+        message:
+          "Invalid date range format.\n" +
+          "Expected: <start>..<end> in ISO 8601 format.\n" +
+          `Example: ${rangeExample}\n` +
+          `Received: "${raw}"`,
+        cause: raw
+      });
+    }
+
+    const start = yield* parseTimestamp(startRaw.trim());
+    const end = yield* parseTimestamp(endRaw.trim());
+
+    if (start.getTime() > end.getTime()) {
+      return yield* CliInputError.make({
+        message: `Range start must be before end. start=${start.toISOString()} end=${end.toISOString()}`,
+        cause: raw
+      });
+    }
+
+    return { start, end };
+  });

package/src/cli/search.ts

@@ -0,0 +1,465 @@
+import { Args, Command, Options } from "@effect/cli";
+import { Effect, Option, Stream } from "effect";
+import { renderTableLegacy } from "./doc/table.js";
+import { BskyClient } from "../services/bsky-client.js";
+import { PostParser } from "../services/post-parser.js";
+import { StoreIndex } from "../services/store-index.js";
+import { renderPostsTable } from "../domain/format.js";
+import { AppConfigService } from "../services/app-config.js";
+import type { FeedGeneratorView, ProfileView } from "../domain/bsky.js";
+import { StoreName } from "../domain/primitives.js";
+import { storeOptions } from "./store.js";
+import { withExamples } from "./help.js";
+import { CliInputError } from "./errors.js";
+import { decodeActor } from "./shared-options.js";
+import { formatSchemaError } from "./shared.js";
+import { writeJson, writeJsonStream, writeText } from "./output.js";
+import { jsonNdjsonTableFormats, resolveOutputFormat } from "./output-format.js";
+
+const queryArg = Args.text({ name: "query" }).pipe(
+  Args.withDescription("Search query string")
+);
+
+const limitOption = Options.integer("limit").pipe(
+  Options.withDescription("Maximum number of results"),
+  Options.optional
+);
+
+const cursorOption = Options.text("cursor").pipe(
+  Options.withDescription("Pagination cursor"),
+  Options.optional
+);
+
+const typeaheadOption = Options.boolean("typeahead").pipe(
+  Options.withDescription("Use prefix typeahead search (handles only)")
+);
+
+const formatOption = Options.choice("format", jsonNdjsonTableFormats).pipe(
+  Options.withDescription("Output format (default: json)"),
+  Options.optional
+);
+
+const storeOption = Options.text("store").pipe(
+  Options.withSchema(StoreName),
+  Options.withDescription("Store name to search")
+);
+
+const storeOptionOptional = storeOption.pipe(Options.optional);
+
+const networkOption = Options.boolean("network").pipe(
+  Options.withDescription("Search the Bluesky network instead of a local store")
+);
+
+const postCursorOption = Options.text("cursor").pipe(
+  Options.withDescription("Pagination cursor (network) or offset (local)"),
+  Options.optional
+);
+
+const sortOption = Options.text("sort").pipe(
+  Options.withDescription("Sort order (local: relevance|newest|oldest, network: top|latest)"),
+  Options.optional
+);
+
+const sinceOption = Options.text("since").pipe(
+  Options.withDescription("Filter network results after datetime (inclusive)"),
+  Options.optional
+);
+
+const untilOption = Options.text("until").pipe(
+  Options.withDescription("Filter network results before datetime (exclusive)"),
+  Options.optional
+);
+
+const mentionsOption = Options.text("mentions").pipe(
+  Options.withDescription("Filter network results by mention (handle or DID)"),
+  Options.optional
+);
+
+const authorOption = Options.text("author").pipe(
+  Options.withDescription("Filter network results by author (handle or DID)"),
+  Options.optional
+);
+
+const langOption = Options.text("lang").pipe(
+  Options.withDescription("Filter network results by language code"),
+  Options.optional
+);
+
+const domainOption = Options.text("domain").pipe(
+  Options.withDescription("Filter network results by link domain"),
+  Options.optional
+);
+
+const urlOption = Options.text("url").pipe(
+  Options.withDescription("Filter network results by URL"),
+  Options.optional
+);
+
+const tagOption = Options.text("tag").pipe(
+  Options.withDescription("Comma-separated tags for network search"),
+  Options.optional
+);
+
+
+type LocalSort = "relevance" | "newest" | "oldest";
+
+const renderProfileTable = (
+  actors: ReadonlyArray<ProfileView>,
+  cursor: string | undefined
+) => {
+  const rows = actors.map((actor) => [
+    actor.handle,
+    actor.displayName ?? "",
+    actor.did
+  ]);
+  const table = renderTableLegacy(["HANDLE", "DISPLAY NAME", "DID"], rows);
+  return cursor ? `${table}\n\nCursor: ${cursor}` : table;
+};
+
+const renderFeedTable = (
+  feeds: ReadonlyArray<FeedGeneratorView>,
+  cursor: string | undefined
+) => {
+  const rows = feeds.map((feed) => [
+    feed.displayName,
+    feed.creator.handle,
+    feed.uri,
+    typeof feed.likeCount === "number" ? String(feed.likeCount) : ""
+  ]);
+  const table = renderTableLegacy(["NAME", "CREATOR", "URI", "LIKES"], rows);
+  return cursor ? `${table}\n\nCursor: ${cursor}` : table;
+};
+
+const handlesCommand = Command.make(
+  "handles",
+  {
+    query: queryArg,
+    limit: limitOption,
+    cursor: cursorOption,
+    typeahead: typeaheadOption,
+    format: formatOption
+  },
+  ({ query, limit, cursor, typeahead, format }) =>
+    Effect.gen(function* () {
+      const appConfig = yield* AppConfigService;
+      if (typeahead && Option.isSome(cursor)) {
+        return yield* CliInputError.make({
+          message: "--cursor is not supported with --typeahead.",
+          cause: { cursor: cursor.value }
+        });
+      }
+      const client = yield* BskyClient;
+      const options = {
+        ...(Option.isSome(limit) ? { limit: limit.value } : {}),
+        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {}),
+        ...(typeahead ? { typeahead: true } : {})
+      };
+      const result = yield* client.searchActors(query, options);
+      const outputFormat = resolveOutputFormat(
+        format,
+        appConfig.outputFormat,
+        jsonNdjsonTableFormats,
+        "json"
+      );
+      if (outputFormat === "ndjson") {
+        yield* writeJsonStream(Stream.fromIterable(result.actors));
+        return;
+      }
+      if (outputFormat === "table") {
+        yield* writeText(renderProfileTable(result.actors, result.cursor));
+        return;
+      }
+      yield* writeJson(result);
+    })
+).pipe(
+  Command.withDescription(
+    withExamples("Search for handles (profiles) on Bluesky", [
+      "skygent search handles \"dan\" --limit 10",
+      "skygent search handles \"alice\" --typeahead"
+    ])
+  )
+);
+
+const feedsCommand = Command.make(
+  "feeds",
+  { query: queryArg, limit: limitOption, cursor: cursorOption, format: formatOption },
+  ({ query, limit, cursor, format }) =>
+    Effect.gen(function* () {
+      const appConfig = yield* AppConfigService;
+      const client = yield* BskyClient;
+      const options = {
+        ...(Option.isSome(limit) ? { limit: limit.value } : {}),
+        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {})
+      };
+      const result = yield* client.searchFeedGenerators(query, options);
+      const outputFormat = resolveOutputFormat(
+        format,
+        appConfig.outputFormat,
+        jsonNdjsonTableFormats,
+        "json"
+      );
+      if (outputFormat === "ndjson") {
+        yield* writeJsonStream(Stream.fromIterable(result.feeds));
+        return;
+      }
+      if (outputFormat === "table") {
+        yield* writeText(renderFeedTable(result.feeds, result.cursor));
+        return;
+      }
+      yield* writeJson(result);
+    })
+).pipe(
+  Command.withDescription(
+    withExamples("Search for feed generators on Bluesky", [
+      "skygent search feeds \"news\" --limit 10"
+    ])
+  )
+);
+
+const postsCommand = Command.make(
+  "posts",
+  {
+    query: queryArg,
+    store: storeOptionOptional,
+    network: networkOption,
+    limit: limitOption,
+    cursor: postCursorOption,
+    sort: sortOption,
+    since: sinceOption,
+    until: untilOption,
+    mentions: mentionsOption,
+    author: authorOption,
+    lang: langOption,
+    domain: domainOption,
+    url: urlOption,
+    tag: tagOption,
+    format: formatOption
+  },
+  ({ query, store, network, limit, cursor, sort, since, until, mentions, author, lang, domain, url, tag, format }) =>
+    Effect.gen(function* () {
+      const appConfig = yield* AppConfigService;
+      if (Option.isSome(limit) && limit.value <= 0) {
+        return yield* CliInputError.make({
+          message: "--limit must be a positive integer.",
+          cause: { limit: limit.value }
+        });
+      }
+      if (network && Option.isSome(store)) {
+        return yield* CliInputError.make({
+          message: "--store cannot be used with --network.",
+          cause: { store: store.value }
+        });
+      }
+      if (!network && Option.isNone(store)) {
+        return yield* CliInputError.make({
+          message: "Provide --store for local search or --network for Bluesky search.",
+          cause: { store: null }
+        });
+      }
+      const hasNetworkOnlyOption =
+        Option.isSome(since) ||
+        Option.isSome(until) ||
+        Option.isSome(mentions) ||
+        Option.isSome(author) ||
+        Option.isSome(lang) ||
+        Option.isSome(domain) ||
+        Option.isSome(url) ||
+        Option.isSome(tag);
+      if (!network && hasNetworkOnlyOption) {
+        return yield* CliInputError.make({
+          message: "Network-only filters require --network.",
+          cause: {
+            since: Option.isSome(since),
+            until: Option.isSome(until),
+            mentions: Option.isSome(mentions),
+            author: Option.isSome(author),
+            lang: Option.isSome(lang),
+            domain: Option.isSome(domain),
+            url: Option.isSome(url),
+            tag: Option.isSome(tag)
+          }
+        });
+      }
+
+      const outputFormat = resolveOutputFormat(
+        format,
+        appConfig.outputFormat,
+        jsonNdjsonTableFormats,
+        "json"
+      );
+      const storeValue = Option.getOrElse(store, () => undefined);
+
+      if (network) {
+        const client = yield* BskyClient;
+        const parser = yield* PostParser;
+        const sortRaw = Option.getOrElse(sort, () => undefined);
+        const sortValue = Option.match(sort, {
+          onNone: () => undefined,
+          onSome: (value) =>
+            value === "top" || value === "latest"
+              ? value
+              : undefined
+        });
+        if (sortRaw && !sortValue) {
+          return yield* CliInputError.make({
+            message: "--sort must be one of: top, latest (for --network).",
+            cause: { sort: sortRaw }
+          });
+        }
+        const cursorValue = Option.map(cursor, (value) => value);
+        const tags = Option.match(tag, {
+          onNone: () => [] as ReadonlyArray<string>,
+          onSome: (value) =>
+            value
+              .split(",")
+              .map((item) => item.trim())
+              .filter((item) => item.length > 0)
+        });
+        const authorValue = Option.match(author, {
+          onNone: () => Effect.void.pipe(Effect.as(undefined)),
+          onSome: (value) =>
+            Effect.gen(function* () {
+              const decoded = yield* decodeActor(value);
+              return String(decoded);
+            })
+        });
+        const mentionsValue = Option.match(mentions, {
+          onNone: () => Effect.void.pipe(Effect.as(undefined)),
+          onSome: (value) =>
+            Effect.gen(function* () {
+              const decoded = yield* decodeActor(value);
+              return String(decoded);
+            })
+        });
+        const parsedAuthor = yield* authorValue;
+        const parsedMentions = yield* mentionsValue;
+        const result = yield* client.searchPosts(query, {
+          ...(Option.isSome(limit) ? { limit: limit.value } : {}),
+          ...(Option.isSome(cursorValue) ? { cursor: cursorValue.value } : {}),
+          ...(sortValue ? { sort: sortValue } : {}),
+          ...(Option.isSome(since) ? { since: since.value } : {}),
+          ...(Option.isSome(until) ? { until: until.value } : {}),
+          ...(parsedMentions ? { mentions: parsedMentions } : {}),
+          ...(parsedAuthor ? { author: parsedAuthor } : {}),
+          ...(Option.isSome(lang) ? { lang: lang.value } : {}),
+          ...(Option.isSome(domain) ? { domain: domain.value } : {}),
+          ...(Option.isSome(url) ? { url: url.value } : {}),
+          ...(tags.length > 0 ? { tags } : {})
+        });
+        const posts = yield* Effect.forEach(
+          result.posts,
+          (raw) =>
+            parser.parsePost(raw).pipe(
+              Effect.mapError((error) =>
+                CliInputError.make({
+                  message: `Failed to parse network post: ${formatSchemaError(error)}`,
+                  cause: error
+                })
+              )
+            ),
+          { concurrency: "unbounded" }
+        );
+        if (outputFormat === "ndjson") {
+          yield* writeJsonStream(Stream.fromIterable(posts));
+          return;
+        }
+        if (outputFormat === "table") {
+          yield* writeText(renderPostsTable(posts));
+          return;
+        }
+        yield* writeJson({
+          query,
+          cursor: result.cursor,
+          hitsTotal: result.hitsTotal,
+          count: posts.length,
+          posts
+        });
+        return;
+      }
+
+      if (!storeValue) {
+        return yield* CliInputError.make({
+          message: "Missing --store for local search.",
+          cause: { store: null }
+        });
+      }
+      const storeRef = yield* storeOptions.loadStoreRef(storeValue);
+      const index = yield* StoreIndex;
+      const parsedCursor = Option.match(cursor, {
+        onNone: () => Effect.succeed(Option.none()),
+        onSome: (value) => {
+          const raw = value;
+          const parsed = Number(raw);
+          if (!Number.isInteger(parsed) || parsed < 0) {
+            return Effect.fail(
+              CliInputError.make({
+                message: "--cursor must be a non-negative integer for local search.",
+                cause: { cursor: raw }
+              })
+            );
+          }
+          return Effect.succeed(Option.some(parsed));
+        }
+      });
+      const cursorValue = yield* parsedCursor;
+      const localSortRaw = Option.getOrElse(sort, () => undefined);
+      const localSort = Option.match(sort, {
+        onNone: () => "relevance" as const,
+        onSome: (value) => {
+          if (value === "relevance" || value === "newest" || value === "oldest") {
+            return value;
+          }
+          return undefined;
+        }
+      }) as LocalSort | undefined;
+      if (localSortRaw && !localSort) {
+        return yield* CliInputError.make({
+          message: "--sort must be one of: relevance, newest, oldest (for local search).",
+          cause: { sort: localSortRaw }
+        });
+      }
+      const input = {
+        query,
+        ...(Option.isSome(limit) ? { limit: limit.value } : {}),
+        ...(Option.isSome(cursorValue) ? { cursor: cursorValue.value } : {}),
+        ...(localSort ? { sort: localSort } : {})
+      };
+      const result = yield* index.searchPosts(storeRef, input);
+
+      if (outputFormat === "ndjson") {
+        const stream = Stream.fromIterable(result.posts);
+        yield* writeJsonStream(stream);
+        return;
+      }
+      if (outputFormat === "table") {
+        yield* writeText(renderPostsTable(result.posts));
+        return;
+      }
+      yield* writeJson({
+        query,
+        cursor: result.cursor,
+        count: result.posts.length,
+        posts: result.posts
+      });
+    })
+).pipe(
+  Command.withDescription(
+    withExamples("Search posts within a local store using FTS", [
+      "skygent search posts \"deep learning\" --store my-store --limit 25",
+      "skygent search posts \"bluesky\" --store my-store --format table",
+      "skygent search posts \"effect\" --store my-store --sort newest",
+      "skygent search posts \"ai\" --network --sort latest"
+    ])
+  )
+);
+
+export const searchCommand = Command.make("search", {}).pipe(
+  Command.withSubcommands([handlesCommand, feedsCommand, postsCommand]),
+  Command.withDescription(
+    withExamples("Search for handles, feeds, or posts", [
+      "skygent search handles \"alice\"",
+      "skygent search feeds \"news\"",
+      "skygent search posts \"ai\" --store my-store"
+    ])
+  )
+);

package/src/cli/shared-options.ts

@@ -0,0 +1,169 @@
+import { Args, Options } from "@effect/cli";
+import { Effect, Option, Schema } from "effect";
+import { Did, Handle, StoreName } from "../domain/primitives.js";
+import { filterDslDescription, filterJsonDescription } from "./filter-help.js";
+import { CliInputError } from "./errors.js";
+import { formatSchemaError } from "./shared.js";
+
+/** --store option with StoreName schema validation */
+export const storeNameOption = Options.text("store").pipe(
+  Options.withSchema(StoreName),
+  Options.withDescription("Store name to write into")
+);
+
+/** --filter DSL option (optional) */
+export const filterOption = Options.text("filter").pipe(
+  Options.withDescription(filterDslDescription()),
+  Options.optional
+);
+
+/** --filter-json option (optional) */
+export const filterJsonOption = Options.text("filter-json").pipe(
+  Options.withDescription(filterJsonDescription()),
+  Options.optional
+);
+
+/** --post-filter DSL option (optional) */
+export const postFilterOption = Options.text("post-filter").pipe(
+  Options.withDescription(filterDslDescription()),
+  Options.optional
+);
+
+/** --post-filter-json option (optional) */
+export const postFilterJsonOption = Options.text("post-filter-json").pipe(
+  Options.withDescription(filterJsonDescription()),
+  Options.optional
+);
+
+/** --quiet flag to suppress progress output */
+export const quietOption = Options.boolean("quiet").pipe(
+  Options.withDescription("Suppress progress output")
+);
+
+/** --refresh flag to update existing posts instead of deduping */
+export const refreshOption = Options.boolean("refresh").pipe(
+  Options.withDescription("Refresh existing posts instead of deduping")
+);
+
+/** --strict flag to stop on first error */
+export const strictOption = Options.boolean("strict").pipe(
+  Options.withDescription("Stop on first error and do not advance the checkpoint")
+);
+
+/** --max-errors option (optional) */
+export const maxErrorsOption = Options.integer("max-errors").pipe(
+  Options.withDescription("Stop after exceeding N errors (default: unlimited)"),
+  Options.optional
+);
+
+/** Positional arg for feed URI */
+export const feedUriArg = Args.text({ name: "uri" }).pipe(
+  Args.withDescription("Bluesky feed URI (at://...)")
+);
+
+/** Positional arg for list URI */
+export const listUriArg = Args.text({ name: "uri" }).pipe(
+  Args.withDescription("Bluesky list URI (at://...)")
+);
+
+/** Positional arg for author handle or DID */
+export const actorArg = Args.text({ name: "actor" }).pipe(
+  Args.withDescription("Bluesky handle or DID")
+);
+
+/** Positional arg for post URI */
+export const postUriArg = Args.text({ name: "uri" }).pipe(
+  Args.withDescription("Bluesky post URI (at://...)")
+);
+
+export const authorFeedFilterValues = [
+  "posts_with_replies",
+  "posts_no_replies",
+  "posts_with_media",
+  "posts_and_author_threads"
+] as const;
+
+/** --filter option for author feed API (optional) */
+export const authorFilterOption = Options.choice(
+  "filter",
+  authorFeedFilterValues
+).pipe(
+  Options.withDescription(
+    "Author feed filter (posts_with_replies, posts_no_replies, posts_with_media, posts_and_author_threads)"
+  ),
+  Options.optional
+);
+
+/** --include-pins flag for author feed API */
+export const includePinsOption = Options.boolean("include-pins").pipe(
+  Options.withDescription("Include pinned posts in author feeds")
+);
+
+/** Validate --max-errors value is non-negative */
+export const parseMaxErrors = (maxErrors: Option.Option<number>) =>
+  Option.match(maxErrors, {
+    onNone: () => Effect.succeed(Option.none()),
+    onSome: (value) =>
+      value < 0
+        ? Effect.fail(
+            CliInputError.make({
+              message: "max-errors must be a non-negative integer.",
+              cause: value
+            })
+          )
+        : Effect.succeed(Option.some(value))
+  });
+
+export const decodeActor = (actor: string) => {
+  if (actor.startsWith("did:")) {
+    return Schema.decodeUnknown(Did)(actor).pipe(
+      Effect.mapError((error) =>
+        CliInputError.make({
+          message: `Invalid DID: ${formatSchemaError(error)}`,
+          cause: { actor }
+        })
+      )
+    );
+  }
+  return Schema.decodeUnknown(Handle)(actor).pipe(
+    Effect.mapError((error) =>
+      CliInputError.make({
+        message: `Invalid handle: ${formatSchemaError(error)}`,
+        cause: { actor }
+      })
+    )
+  );
+};
+
+export const parseLimit = (limit: Option.Option<number>) =>
+  Option.match(limit, {
+    onNone: () => Effect.succeed(Option.none()),
+    onSome: (value) =>
+      value <= 0
+        ? Effect.fail(
+            CliInputError.make({
+              message: "--limit must be a positive integer.",
+              cause: value
+            })
+          )
+        : Effect.succeed(Option.some(value))
+  });
+
+export const parseBoundedIntOption = (
+  value: Option.Option<number>,
+  name: string,
+  min: number,
+  max: number
+) =>
+  Option.match(value, {
+    onNone: () => Effect.succeed(Option.none()),
+    onSome: (raw) =>
+      raw < min || raw > max
+        ? Effect.fail(
+            CliInputError.make({
+              message: `${name} must be between ${min} and ${max}.`,
+              cause: raw
+            })
+          )
+        : Effect.succeed(Option.some(raw))
+  });

package/src/cli/shared.ts

@@ -0,0 +1,20 @@
+export { formatSchemaError } from "../services/shared.js";
+
+/** Safely parse JSON, returning `undefined` on failure. */
+export const safeParseJson = (raw: string): unknown => {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+};
+
+/** Format schema issues into an array of "path: message" strings. */
+export const issueDetails = (
+  issues: ReadonlyArray<{ readonly path: ReadonlyArray<unknown>; readonly message: string }>
+) =>
+  issues.map((issue) => {
+    const path =
+      issue.path.length > 0 ? issue.path.map((entry) => String(entry)).join(".") : "value";
+    return `${path}: ${issue.message}`;
+  });