@mepuka/skygent 0.2.0 → 0.3.0

package/src/cli/search.ts

@@ -1,12 +1,11 @@
 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 { storeOptions } from "./store.js";
 import { withExamples } from "./help.js";
@@ -14,20 +13,21 @@ 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";
+import { parseLimit } from "./shared-options.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 +50,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(
@@ -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 } = yield* 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 } = yield* 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,9 @@ 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 parsedLimit = yield* parseLimit(limit);
+      const limitValue = Option.getOrUndefined(parsedLimit);
       if (network && Option.isSome(store)) {
         return yield* CliInputError.make({
           message: "--store cannot be used with --network.",
@@ -281,12 +259,6 @@ const postsCommand = Command.make(
         });
       }
 
-      const outputFormat = resolveOutputFormat(
-        format,
-        appConfig.outputFormat,
-        jsonNdjsonTableFormats,
-        "json"
-      );
       const storeValue = Option.getOrElse(store, () => undefined);
 
       if (network) {
@@ -331,13 +303,13 @@ const postsCommand = Command.make(
               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 = yield* authorValue;
+      const parsedMentions = yield* mentionsValue;
+      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 +331,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 +393,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.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}`;
-  });

package/src/cli/store-errors.ts

@@ -1,23 +1,31 @@
 import { ParseResult } from "effect";
-import { safeParseJson, issueDetails } from "./shared.js";
+import { safeParseJson, issueDetails } 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,
@@ -36,7 +44,7 @@ export const formatStoreConfigParseError = (
   if (jsonParseIssue) {
     return formatAgentError({
       error: "StoreConfigJsonParseError",
-      message: "Invalid JSON in --config-json.",
+      message: `Invalid JSON in --config-json. ${storeConfigDocHint}`,
       received: raw,
       details: [
         jsonParseIssue.message,
@@ -49,7 +57,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 +68,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 +76,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 };
     }

package/src/cli/store.ts

@@ -14,12 +14,13 @@ import { StoreCleaner } from "../services/store-cleaner.js";
 import { LineageStore } from "../services/lineage-store.js";
 import { CliInputError } from "./errors.js";
 import { OutputManager } from "../services/output-manager.js";
-import { formatStoreConfigParseError } from "./store-errors.js";
+import { formatStoreConfigHelp, formatStoreConfigParseError } from "./store-errors.js";
 import { formatFilterExpr } from "../domain/filter-describe.js";
 import { CliPreferences } from "./preferences.js";
 import { StoreStats } from "../services/store-stats.js";
 import { withExamples } from "./help.js";
 import { resolveOutputFormat, treeTableJsonFormats } from "./output-format.js";
+import { StoreRenamer } from "../services/store-renamer.js";
 import {
   buildStoreTreeData,
   renderStoreTree,
@@ -33,6 +34,14 @@ const storeNameArg = Args.text({ name: "name" }).pipe(
   Args.withSchema(StoreName),
   Args.withDescription("Store name")
 );
+const storeRenameFromArg = Args.text({ name: "from" }).pipe(
+  Args.withSchema(StoreName),
+  Args.withDescription("Existing store name")
+);
+const storeRenameToArg = Args.text({ name: "to" }).pipe(
+  Args.withSchema(StoreName),
+  Args.withDescription("New store name")
+);
 const storeNameOption = Options.text("store").pipe(
   Options.withSchema(StoreName),
   Options.withDescription("Store name")
@@ -254,6 +263,27 @@ export const storeDelete = Command.make(
   )
 );
 
+export const storeRename = Command.make(
+  "rename",
+  { from: storeRenameFromArg, to: storeRenameToArg },
+  ({ from, to }) =>
+    Effect.gen(function* () {
+      if (from === to) {
+        return yield* CliInputError.make({
+          message: "Old and new store names must be different.",
+          cause: { from, to }
+        });
+      }
+      const renamer = yield* StoreRenamer;
+      const result = yield* renamer.rename(from, to);
+      yield* writeJson(result);
+    })
+).pipe(
+  Command.withDescription(
+    withExamples("Rename a store", ["skygent store rename old-name new-name"])
+  )
+);
+
 export const storeMaterialize = Command.make(
   "materialize",
   { name: storeNameArg, filter: filterNameOption },
@@ -267,7 +297,9 @@ export const storeMaterialize = Command.make(
 
       if (config.filters.length === 0) {
         return yield* CliInputError.make({
-          message: `Store "${name}" has no configured filters to materialize. Update the store config to add filters.`,
+          message: formatStoreConfigHelp(
+            `Store "${name}" has no configured filters to materialize. Add filters to the store config.`
+          ),
           cause: { store: name }
         });
       }
@@ -378,6 +410,7 @@ export const storeCommand = Command.make("store", {}).pipe(
     storeCreate,
     storeList,
     storeShow,
+    storeRename,
     storeDelete,
     storeMaterialize,
     storeStats,

package/src/cli/stream-merge.ts

@@ -0,0 +1,105 @@
+import { Chunk, Effect, Option, Order, Stream } from "effect";
+
+export const mergeOrderedStreams = <A, E, R>(
+  streams: ReadonlyArray<Stream.Stream<A, E, R>>,
+  order: Order.Order<A>
+): Stream.Stream<A, E, R> => {
+  if (streams.length === 0) {
+    return Stream.empty;
+  }
+
+  return Stream.unwrapScoped(
+    Effect.gen(function* () {
+      const pulls = yield* Effect.forEach(streams, (stream) => Stream.toPull(stream), {
+        discard: false
+      });
+
+      const buffers: Array<ReadonlyArray<A>> = pulls.map(() => []);
+      const indices: number[] = pulls.map(() => 0);
+      const heads: Array<A | undefined> = pulls.map(() => undefined);
+      let active = pulls.length;
+
+      const pullChunk = (index: number) =>
+        pulls[index]!.pipe(
+          Effect.map(Option.some),
+          Effect.catchAll((cause) =>
+            Option.match(cause, {
+              onNone: () => Effect.succeed(Option.none()),
+              onSome: (error) => Effect.fail(error)
+            })
+          )
+        );
+
+      const nextValue = (index: number): Effect.Effect<Option.Option<A>, E, R> =>
+        Effect.gen(function* () {
+          while (true) {
+            const buffer = buffers[index] ?? [];
+            const position = indices[index] ?? 0;
+            if (position < buffer.length) {
+              const value = buffer[position]!;
+              indices[index] = position + 1;
+              return Option.some(value);
+            }
+
+            const nextChunkOption = yield* pullChunk(index);
+            if (Option.isNone(nextChunkOption)) {
+              return Option.none<A>();
+            }
+            const nextChunk = Chunk.toReadonlyArray(nextChunkOption.value);
+            if (nextChunk.length === 0) {
+              continue;
+            }
+            buffers[index] = nextChunk;
+            indices[index] = 1;
+            return Option.some(nextChunk[0]!);
+          }
+        });
+
+      for (let index = 0; index < pulls.length; index += 1) {
+        const next = yield* nextValue(index);
+        if (Option.isNone(next)) {
+          active -= 1;
+          heads[index] = undefined;
+        } else {
+          heads[index] = next.value;
+        }
+      }
+
+      const pull: Effect.Effect<Chunk.Chunk<A>, Option.Option<E>, R> =
+        Effect.gen(function* () {
+          if (active === 0) {
+            return yield* Effect.fail(Option.none<E>());
+          }
+
+          let selectedIndex = -1;
+          let selectedValue: A | undefined;
+          for (let index = 0; index < heads.length; index += 1) {
+            const value = heads[index];
+            if (value === undefined) continue;
+            if (selectedIndex < 0 || order(value, selectedValue as A) < 0) {
+              selectedIndex = index;
+              selectedValue = value;
+            }
+          }
+
+          if (selectedIndex < 0 || selectedValue === undefined) {
+            return yield* Effect.fail(Option.none<E>());
+          }
+
+          const next = yield* nextValue(selectedIndex).pipe(
+            Effect.mapError(Option.some)
+          );
+          if (Option.isNone(next)) {
+            heads[selectedIndex] = undefined;
+            active -= 1;
+          } else {
+            heads[selectedIndex] = next.value;
+          }
+
+          return Chunk.of(selectedValue);
+        });
+
+      return Stream.fromPull(Effect.succeed(pull));
+    })
+  );
+};