@mepuka/skygent 0.2.0 → 0.3.1

package/src/cli/search.ts

@@ -1,33 +1,31 @@
 import { Args, Command, Options } from "@effect/cli";
 import { Effect, Option, Stream } from "effect";
-import { renderTableLegacy } from "./doc/table.js";
+import { renderFeedTable, renderProfileTable } from "./doc/table-renderers.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 { ActorId, 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";
+import { jsonNdjsonTableFormats } from "./output-format.js";
+import { emitWithFormat } from "./output-render.js";
+import { cursorOption as baseCursorOption, limitOption as baseLimitOption, parsePagination } from "./pagination.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 limitOption = baseLimitOption.pipe(
+  Options.withDescription("Maximum number of results")
 );
 
-const cursorOption = Options.text("cursor").pipe(
-  Options.withDescription("Pagination cursor"),
-  Options.optional
+const cursorOption = baseCursorOption.pipe(
+  Options.withDescription("Pagination cursor")
 );
 
 const typeaheadOption = Options.boolean("typeahead").pipe(
@@ -50,9 +48,8 @@ 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 postCursorOption = baseCursorOption.pipe(
+  Options.withDescription("Pagination cursor (network) or offset (local)")
 );
 
 const sortOption = Options.text("sort").pipe(
@@ -71,11 +68,13 @@ const untilOption = Options.text("until").pipe(
 );
 
 const mentionsOption = Options.text("mentions").pipe(
+  Options.withSchema(ActorId),
   Options.withDescription("Filter network results by mention (handle or DID)"),
   Options.optional
 );
 
 const authorOption = Options.text("author").pipe(
+  Options.withSchema(ActorId),
   Options.withDescription("Filter network results by author (handle or DID)"),
   Options.optional
 );
@@ -100,35 +99,21 @@ const tagOption = Options.text("tag").pipe(
   Options.optional
 );
 
+const requireNonEmptyQuery = (raw: string) =>
+  Effect.gen(function* () {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+      return yield* CliInputError.make({
+        message: "Search query must be non-empty.",
+        cause: { query: raw }
+      });
+    }
+    return trimmed;
+  });
 
-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;
-};
+type LocalSort = "relevance" | "newest" | "oldest";
 
-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",
@@ -142,6 +127,7 @@ const handlesCommand = Command.make(
   ({ query, limit, cursor, typeahead, format }) =>
     Effect.gen(function* () {
       const appConfig = yield* AppConfigService;
+      const queryValue = yield* requireNonEmptyQuery(query);
       if (typeahead && Option.isSome(cursor)) {
         return yield* CliInputError.make({
           message: "--cursor is not supported with --typeahead.",
@@ -149,27 +135,24 @@ const handlesCommand = Command.make(
         });
       }
       const client = yield* BskyClient;
+      const { limit: limitValue, cursor: cursorValue } = parsePagination(limit, cursor);
       const options = {
-        ...(Option.isSome(limit) ? { limit: limit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {}),
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {}),
         ...(typeahead ? { typeahead: true } : {})
       };
-      const result = yield* client.searchActors(query, options);
-      const outputFormat = resolveOutputFormat(
+      const result = yield* client.searchActors(queryValue, options);
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson: writeJsonStream(Stream.fromIterable(result.actors)),
+          table: writeText(renderProfileTable(result.actors, result.cursor))
+        }
       );
-      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(
@@ -186,27 +169,25 @@ const feedsCommand = Command.make(
   ({ query, limit, cursor, format }) =>
     Effect.gen(function* () {
       const appConfig = yield* AppConfigService;
+      const queryValue = yield* requireNonEmptyQuery(query);
       const client = yield* BskyClient;
+      const { limit: limitValue, cursor: cursorValue } = parsePagination(limit, cursor);
       const options = {
-        ...(Option.isSome(limit) ? { limit: limit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {})
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {})
       };
-      const result = yield* client.searchFeedGenerators(query, options);
-      const outputFormat = resolveOutputFormat(
+      const result = yield* client.searchFeedGenerators(queryValue, options);
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson: writeJsonStream(Stream.fromIterable(result.feeds)),
+          table: writeText(renderFeedTable(result.feeds, result.cursor))
+        }
       );
-      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(
@@ -238,12 +219,8 @@ const postsCommand = Command.make(
   ({ 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 }
-        });
-      }
+      const queryValue = yield* requireNonEmptyQuery(query);
+      const limitValue = Option.getOrUndefined(limit);
       if (network && Option.isSome(store)) {
         return yield* CliInputError.make({
           message: "--store cannot be used with --network.",
@@ -281,12 +258,6 @@ const postsCommand = Command.make(
         });
       }
 
-      const outputFormat = resolveOutputFormat(
-        format,
-        appConfig.outputFormat,
-        jsonNdjsonTableFormats,
-        "json"
-      );
       const storeValue = Option.getOrElse(store, () => undefined);
 
       if (network) {
@@ -315,29 +286,13 @@ const postsCommand = Command.make(
               .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 } : {}),
+        const parsedAuthor = Option.getOrUndefined(author);
+        const parsedMentions = Option.getOrUndefined(mentions);
+      const result = yield* client.searchPosts(queryValue, {
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(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 } : {}),
@@ -359,21 +314,23 @@ const postsCommand = Command.make(
             ),
           { 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
-        });
+        yield* emitWithFormat(
+          format,
+          appConfig.outputFormat,
+          jsonNdjsonTableFormats,
+          "json",
+          {
+            json: writeJson({
+              query: queryValue,
+              cursor: result.cursor,
+              hitsTotal: result.hitsTotal,
+              count: posts.length,
+              posts
+            }),
+            ndjson: writeJsonStream(Stream.fromIterable(posts)),
+            table: writeText(renderPostsTable(posts))
+          }
+        );
         return;
       }
 
@@ -419,28 +376,28 @@ const postsCommand = Command.make(
         });
       }
       const input = {
-        query,
-        ...(Option.isSome(limit) ? { limit: limit.value } : {}),
+        query: queryValue,
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
         ...(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
-      });
+      yield* emitWithFormat(
+        format,
+        appConfig.outputFormat,
+        jsonNdjsonTableFormats,
+        "json",
+        {
+          json: writeJson({
+            query: queryValue,
+            cursor: result.cursor,
+            count: result.posts.length,
+            posts: result.posts
+          }),
+          ndjson: writeJsonStream(Stream.fromIterable(result.posts)),
+          table: writeText(renderPostsTable(result.posts))
+        }
+      );
     })
 ).pipe(
   Command.withDescription(

package/src/cli/shared-options.ts

@@ -1,9 +1,10 @@
 import { Args, Options } from "@effect/cli";
-import { Effect, Option, Schema } from "effect";
-import { Did, Handle, StoreName } from "../domain/primitives.js";
+import { Effect, Schema } from "effect";
+import { ActorId, AtUri, PostUri, StoreName } from "../domain/primitives.js";
 import { filterDslDescription, filterJsonDescription } from "./filter-help.js";
 import { CliInputError } from "./errors.js";
 import { formatSchemaError } from "./shared.js";
+import { NonNegativeInt } from "./option-schemas.js";
 
 /** --store option with StoreName schema validation */
 export const storeNameOption = Options.text("store").pipe(
@@ -52,27 +53,32 @@ export const strictOption = Options.boolean("strict").pipe(
 
 /** --max-errors option (optional) */
 export const maxErrorsOption = Options.integer("max-errors").pipe(
+  Options.withSchema(NonNegativeInt),
   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.withSchema(AtUri),
   Args.withDescription("Bluesky feed URI (at://...)")
 );
 
 /** Positional arg for list URI */
 export const listUriArg = Args.text({ name: "uri" }).pipe(
+  Args.withSchema(AtUri),
   Args.withDescription("Bluesky list URI (at://...)")
 );
 
 /** Positional arg for author handle or DID */
 export const actorArg = Args.text({ name: "actor" }).pipe(
+  Args.withSchema(ActorId),
   Args.withDescription("Bluesky handle or DID")
 );
 
 /** Positional arg for post URI */
 export const postUriArg = Args.text({ name: "uri" }).pipe(
+  Args.withSchema(PostUri),
   Args.withDescription("Bluesky post URI (at://...)")
 );
 
@@ -100,70 +106,12 @@ export const includePinsOption = Options.boolean("include-pins").pipe(
 );
 
 /** 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(
+export const decodeActor = (actor: string) =>
+  Schema.decodeUnknown(ActorId)(actor).pipe(
     Effect.mapError((error) =>
       CliInputError.make({
-        message: `Invalid handle: ${formatSchemaError(error)}`,
+        message: `Invalid actor: ${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

@@ -1,20 +1 @@
-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}`;
-  });
+export { formatParseError, formatSchemaError } from "../services/shared.js";

package/src/cli/store-errors.ts

@@ -1,23 +1,31 @@
 import { ParseResult } from "effect";
-import { safeParseJson, issueDetails } from "./shared.js";
+import { safeParseJson, issueDetails, findJsonParseIssue, jsonParseTip } from "./parse-errors.js";
 import { formatAgentError } from "./errors.js";
 
 const storeConfigExample = {
   format: { json: true, markdown: false },
   autoSync: false,
-  filters: [
-    {
-      name: "tech",
-      expr: { _tag: "Hashtag", tag: "#tech" },
-      output: { path: "views/tech", json: true, markdown: true }
-    }
-  ]
+  filters: []
 };
 
+const storeConfigExampleJson = JSON.stringify(storeConfigExample);
+const storeConfigDocHint = "See docs/cli.md for a minimal StoreConfig JSON example.";
+
 
 const hasPath = (issue: { readonly path: ReadonlyArray<unknown> }, key: string) =>
   issue.path.length > 0 && issue.path[0] === key;
 
+export const formatStoreConfigHelp = (
+  message: string,
+  error = "StoreConfigValidationError"
+): string =>
+  formatAgentError({
+    error,
+    message: `${message} ${storeConfigDocHint}`,
+    expected: storeConfigExample,
+    fix: `Start with: --config-json '${storeConfigExampleJson}'`
+  });
+
 
 export const formatStoreConfigParseError = (
   error: ParseResult.ParseError,
@@ -27,20 +35,16 @@ export const formatStoreConfigParseError = (
   const received = safeParseJson(raw);
   const receivedValue = received === undefined ? raw : received;
 
-  const jsonParseIssue = issues.find(
-    (issue) =>
-      issue._tag === "Transformation" &&
-      typeof issue.message === "string" &&
-      issue.message.startsWith("JSON Parse error")
-  );
+  const jsonParseIssue = findJsonParseIssue(issues);
   if (jsonParseIssue) {
+    const jsonMessage = jsonParseIssue.message ?? "Invalid JSON input.";
     return formatAgentError({
       error: "StoreConfigJsonParseError",
-      message: "Invalid JSON in --config-json.",
+      message: `Invalid JSON in --config-json. ${storeConfigDocHint}`,
       received: raw,
       details: [
-        jsonParseIssue.message,
-        "Tip: wrap JSON in single quotes to avoid shell escaping issues."
+        jsonMessage,
+        jsonParseTip
       ],
       expected: storeConfigExample
     });
@@ -49,7 +53,7 @@ export const formatStoreConfigParseError = (
   if (issues.some((issue) => issue._tag === "Missing" && hasPath(issue, "filters"))) {
     return formatAgentError({
       error: "StoreConfigValidationError",
-      message: "Store config requires a filters array.",
+      message: `Store config requires a filters array. ${storeConfigDocHint}`,
       received: receivedValue,
       expected: storeConfigExample,
       fix:
@@ -60,7 +64,7 @@ export const formatStoreConfigParseError = (
   if (issues.some((issue) => hasPath(issue, "filters"))) {
     return formatAgentError({
       error: "StoreConfigValidationError",
-      message: "Store config filters must include name, expr, and output fields.",
+      message: `Store config filters must include name, expr, and output fields. ${storeConfigDocHint}`,
       received: receivedValue,
       expected: storeConfigExample,
       fix: "Each filter requires name, expr (filter JSON), and output (path/json/markdown).",
@@ -68,12 +72,15 @@ export const formatStoreConfigParseError = (
     });
   }
 
+  const details = issueDetails(issues);
+  const primaryIssue = details[0];
+  const issueHint = primaryIssue ? ` (${primaryIssue})` : "";
   return formatAgentError({
     error: "StoreConfigValidationError",
-    message: "Store config failed validation.",
+    message: `Store config failed validation${issueHint}. ${storeConfigDocHint}`,
     received: receivedValue,
     expected: storeConfigExample,
-    details: issueDetails(issues),
+    details,
     fix:
       "Check required fields (format, autoSync, filters). For ingestion filters, use --filter/--filter-json on sync/query."
   });

package/src/cli/store-tree.ts

@@ -1,5 +1,5 @@
 import * as Doc from "@effect/printer/Doc";
-import { Chunk, Context, Effect, Option } from "effect";
+import { Chunk, Context, Effect, Option, Order } from "effect";
 import { StoreIndex } from "../services/store-index.js";
 import { StoreManager } from "../services/store-manager.js";
 import { LineageStore } from "../services/lineage-store.js";
@@ -9,6 +9,7 @@ import { StoreEventLog } from "../services/store-event-log.js";
 import { DataSource } from "../domain/sync.js";
 import type { FilterExpr } from "../domain/filter.js";
 import { formatFilterExpr } from "../domain/filter-describe.js";
+import { updatedAtOrder } from "../domain/order.js";
 import type { StoreName } from "../domain/primitives.js";
 import type { StoreRef } from "../domain/store.js";
 import type { StoreLineage } from "../domain/derivation.js";
@@ -123,9 +124,10 @@ const resolveSyncInfo = (
     if (candidates.length === 0) {
       return { syncStatus: "unknown" as const };
     }
-    const latest = candidates.sort(
-      (a, b) => b.updatedAt.getTime() - a.updatedAt.getTime()
-    )[0];
+    const checkpointOrder = updatedAtOrder<(typeof candidates)[number]>();
+    const latest = candidates.reduce((acc, candidate) =>
+      Order.max(checkpointOrder)(acc, candidate)
+    );
     if (!latest) {
       return { syncStatus: "unknown" as const };
     }