@mepuka/skygent 0.2.0 → 0.3.1

package/src/cli/feed.ts

@@ -1,36 +1,38 @@
 import { Args, Command, Options } from "@effect/cli";
-import { Effect, Option, Stream } from "effect";
+import { Effect, Option, Schema, Stream } from "effect";
 import { renderTableLegacy } from "./doc/table.js";
+import { renderFeedTable } from "./doc/table-renderers.js";
 import { BskyClient } from "../services/bsky-client.js";
-import type { FeedGeneratorView } from "../domain/bsky.js";
 import { AppConfigService } from "../services/app-config.js";
-import { decodeActor, parseLimit } from "./shared-options.js";
+import type { FeedGeneratorView } from "../domain/bsky.js";
+import { AtUri } from "../domain/primitives.js";
+import { CliPreferences } from "./preferences.js";
+import { compactFeedGeneratorView } from "./compact-output.js";
+import { actorArg } from "./shared-options.js";
 import { CliInputError } from "./errors.js";
 import { withExamples } from "./help.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 feedUriArg = Args.text({ name: "uri" }).pipe(
+  Args.withSchema(AtUri),
   Args.withDescription("Bluesky feed URI (at://...)")
 );
 
 const feedUrisArg = Args.text({ name: "uri" }).pipe(
   Args.repeated,
+  Args.withSchema(Schema.mutable(Schema.Array(AtUri))),
   Args.withDescription("Feed URIs to fetch")
 );
 
-const actorArg = Args.text({ name: "actor" }).pipe(
-  Args.withDescription("Bluesky handle or DID")
-);
-
-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 formatOption = Options.choice("format", jsonNdjsonTableFormats).pipe(
@@ -38,19 +40,17 @@ const formatOption = Options.choice("format", jsonNdjsonTableFormats).pipe(
   Options.optional
 );
 
-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 ensureSupportedFormat = (
+  format: Option.Option<typeof jsonNdjsonTableFormats[number]>,
+  configFormat: string
+) =>
+  Option.isNone(format) && configFormat === "markdown"
+    ? CliInputError.make({
+        message: 'Output format "markdown" is not supported for feed commands. Use --format json|ndjson|table.',
+        cause: { format: configFormat }
+      })
+    : Effect.void;
+
 
 const renderFeedInfoTable = (
   view: FeedGeneratorView,
@@ -68,19 +68,27 @@ const showCommand = Command.make(
   ({ uri, format }) =>
     Effect.gen(function* () {
       const appConfig = yield* AppConfigService;
+      yield* ensureSupportedFormat(format, appConfig.outputFormat);
+      const preferences = yield* CliPreferences;
       const client = yield* BskyClient;
       const result = yield* client.getFeedGenerator(uri);
-      const outputFormat = resolveOutputFormat(
+      const payload = preferences.compact
+        ? {
+            ...result,
+            view: compactFeedGeneratorView(result.view)
+          }
+        : result;
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(payload),
+          ndjson: writeJson(payload),
+          table: writeText(renderFeedInfoTable(result.view, result.isOnline, result.isValid))
+        }
       );
-      if (outputFormat === "table") {
-        yield* writeText(renderFeedInfoTable(result.view, result.isOnline, result.isValid));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -96,6 +104,8 @@ const batchCommand = Command.make(
   ({ uris, format }) =>
     Effect.gen(function* () {
       const appConfig = yield* AppConfigService;
+      yield* ensureSupportedFormat(format, appConfig.outputFormat);
+      const preferences = yield* CliPreferences;
       const client = yield* BskyClient;
       if (uris.length === 0) {
         return yield* CliInputError.make({
@@ -104,21 +114,24 @@ const batchCommand = Command.make(
         });
       }
       const result = yield* client.getFeedGenerators(uris);
-      const outputFormat = resolveOutputFormat(
+      const feeds = preferences.compact
+        ? result.feeds.map(compactFeedGeneratorView)
+        : result.feeds;
+      const payload = { ...result, feeds };
+      const feedsStream = Stream.fromIterable(
+        feeds as ReadonlyArray<FeedGeneratorView | ReturnType<typeof compactFeedGeneratorView>>
+      );
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(payload),
+          ndjson: writeJsonStream(feedsStream),
+          table: writeText(renderFeedTable(result.feeds, undefined))
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.feeds));
-        return;
-      }
-      if (outputFormat === "table") {
-        yield* writeText(renderFeedTable(result.feeds, undefined));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -134,28 +147,32 @@ const byActorCommand = Command.make(
   ({ actor, limit, cursor, format }) =>
     Effect.gen(function* () {
       const appConfig = yield* AppConfigService;
+      yield* ensureSupportedFormat(format, appConfig.outputFormat);
+      const preferences = yield* CliPreferences;
       const client = yield* BskyClient;
-      const parsedLimit = yield* parseLimit(limit);
-      const resolvedActor = yield* decodeActor(actor);
-      const result = yield* client.getActorFeeds(resolvedActor, {
-        ...(Option.isSome(parsedLimit) ? { limit: parsedLimit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {})
+      const { limit: limitValue, cursor: cursorValue } = parsePagination(limit, cursor);
+      const result = yield* client.getActorFeeds(actor, {
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {})
       });
-      const outputFormat = resolveOutputFormat(
+      const feeds = preferences.compact
+        ? result.feeds.map(compactFeedGeneratorView)
+        : result.feeds;
+      const payload = { ...result, feeds };
+      const feedsStream = Stream.fromIterable(
+        feeds as ReadonlyArray<FeedGeneratorView | ReturnType<typeof compactFeedGeneratorView>>
+      );
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(payload),
+          ndjson: writeJsonStream(feedsStream),
+          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(

package/src/cli/filter-dsl.ts

@@ -1,14 +1,15 @@
-import { Context, Duration, Effect, Schema } from "effect";
+import { Clock, Context, Duration, Effect, Schema } from "effect";
 import { formatSchemaError } from "./shared.js";
 import type { FilterEngagement, FilterExpr } from "../domain/filter.js";
 import { all, and, none, not, or } from "../domain/filter.js";
 import type { FilterErrorPolicy } from "../domain/policies.js";
 import { ExcludeOnError, IncludeOnError, RetryOnError } from "../domain/policies.js";
-import { Handle, Hashtag, StoreName } from "../domain/primitives.js";
+import { Handle, Hashtag, StoreName, Timestamp } from "../domain/primitives.js";
 import { FilterLibrary } from "../services/filter-library.js";
 import { FilterLibraryError, FilterNotFound } from "../domain/errors.js";
 import { CliInputError } from "./errors.js";
 import { parseRange } from "./range.js";
+import { parseDurationInput, parseTimeInput } from "./time.js";
 
 type Token =
   | { readonly _tag: "Word"; readonly value: string; readonly position: number }
@@ -212,7 +213,8 @@ const normalizeOptionKey = (key: string) =>
 const normalizeFilterKey = (key: string) => key.trim().toLowerCase();
 
 const unsupportedFilterKeys = new Map<string, string>([
-  ["label", "Label filters are not supported yet."]
+  ["label", "Label filters are not supported yet."],
+  ["labels", "Label filters are not supported yet."]
 ]);
 
 const filterKeyHints = new Map<string, string>([
@@ -235,7 +237,10 @@ const filterKeyHints = new Map<string, string>([
   ["hashtagin", "hashtagin:#ai,#ml"],
   ["tags", "hashtagin:#ai,#ml"],
   ["hashtags", "hashtagin:#ai,#ml"],
-  ["engagement", "engagement:minLikes=100"]
+  ["engagement", "engagement:minLikes=100"],
+  ["since", "since:24h"],
+  ["until", "until:2026-01-01T00:00:00Z"],
+  ["age", "age:<24h"]
 ]);
 
 type FilterSuggestion = {
@@ -296,6 +301,18 @@ const filterSuggestions: ReadonlyArray<FilterSuggestion> = [
     keys: ["engagement"],
     suggestions: ["engagement:minLikes=100"]
   },
+  {
+    keys: ["since"],
+    suggestions: ["since:24h"]
+  },
+  {
+    keys: ["until"],
+    suggestions: ["until:2026-01-01T00:00:00Z"]
+  },
+  {
+    keys: ["age"],
+    suggestions: ["age:<24h"]
+  },
   {
     keys: ["authorin", "authors"],
     suggestions: ["authorin:alice,bob"]
@@ -315,6 +332,7 @@ const defaultFilterExamples = [
   "hashtag:#ai",
   "text:\"hello\""
 ];
+const filterHelpHint = " Tip: run \"skygent filter help\" for all predicates.";
 
 const uniqueSuggestions = (items: ReadonlyArray<string>) =>
   Array.from(new Set(items));
@@ -826,7 +844,8 @@ class Parser {
   constructor(
     private readonly input: string,
     private readonly tokens: ReadonlyArray<Token>,
-    private readonly library: FilterLibraryService
+    private readonly library: FilterLibraryService,
+    private readonly now: Date
   ) {}
 
   parse = (): Effect.Effect<FilterExpr, CliInputError> => {
@@ -1031,7 +1050,7 @@ class Parser {
         const unsupported = unsupportedFilterKeys.get(lower);
         if (unsupported) {
           return yield* self.fail(
-            `Unknown filter type "${value}". ${unsupported}`,
+            `Unknown filter type "${value}". ${unsupported}${filterHelpHint}`,
             token.position
           );
         }
@@ -1043,7 +1062,7 @@ class Parser {
           );
         }
         return yield* self.fail(
-          "Expected a filter expression like 'hashtag:#ai' or 'author:handle'.",
+          `Expected a filter expression like 'hashtag:#ai' or 'author:handle'.${filterHelpHint}`,
           token.position
         );
       }
@@ -1111,6 +1130,8 @@ class Parser {
       const { value: baseValueRaw, valuePosition: basePosition, options } =
         yield* parseValueOptions(self.input, rawValue, valuePosition, optionMode);
       const baseValue = stripQuotes(baseValueRaw);
+      const timeError = (message: string, cause?: unknown) =>
+        failAt(self.input, basePosition, message);
 
       switch (key) {
         case "author":
@@ -1197,7 +1218,10 @@ class Parser {
             case "embeds":
               return { _tag: "HasEmbed" };
             default:
-              return yield* self.fail(`Unknown has: filter "${baseValue}".`, token.position);
+              return yield* self.fail(
+                `Unknown has: filter "${baseValue}". Use images|video|links|media|embed.`,
+                token.position
+              );
           }
         }
         case "engagement": {
@@ -1296,6 +1320,105 @@ class Parser {
           yield* ensureNoUnknownOptions(options, self.input);
           return { _tag: "DateRange", start: range.start, end: range.end };
         }
+        case "since": {
+          if (baseValue.length === 0) {
+            return yield* self.fail(`Missing value for "${key}".`, token.position);
+          }
+          const start = yield* parseTimeInput(baseValue, self.now, {
+            label: "since",
+            onError: timeError
+          });
+          const end = self.now;
+          if (start.getTime() >= end.getTime()) {
+            return yield* self.fail(
+              "Since value must be before now.",
+              basePosition
+            );
+          }
+          yield* ensureNoUnknownOptions(options, self.input);
+          return {
+            _tag: "DateRange",
+            start: yield* self.asTimestamp(start, basePosition),
+            end: yield* self.asTimestamp(end, basePosition)
+          };
+        }
+        case "until": {
+          if (baseValue.length === 0) {
+            return yield* self.fail(`Missing value for "${key}".`, token.position);
+          }
+          const end = yield* parseTimeInput(baseValue, self.now, {
+            label: "until",
+            onError: timeError
+          });
+          const start = new Date(0);
+          if (start.getTime() >= end.getTime()) {
+            return yield* self.fail(
+              "Until value must be after the epoch (1970-01-01T00:00:00Z).",
+              basePosition
+            );
+          }
+          yield* ensureNoUnknownOptions(options, self.input);
+          return {
+            _tag: "DateRange",
+            start: yield* self.asTimestamp(start, basePosition),
+            end: yield* self.asTimestamp(end, basePosition)
+          };
+        }
+        case "age": {
+          if (baseValue.length === 0) {
+            return yield* self.fail(`Missing value for "${key}".`, token.position);
+          }
+          const comparatorMatch = /^(<=|>=|<|>)/.exec(baseValue.trim());
+          const comparator = comparatorMatch?.[1];
+          const durationRaw = comparator
+            ? baseValue.trim().slice(comparator.length).trim()
+            : baseValue.trim();
+          if (durationRaw.length === 0) {
+            return yield* self.fail("Age filter requires a duration.", basePosition);
+          }
+          const duration = yield* parseDurationInput(durationRaw, {
+            label: "age",
+            onError: timeError
+          });
+          const durationMillis = Duration.toMillis(duration);
+          if (durationMillis <= 0) {
+            return yield* self.fail(
+              "Age duration must be greater than zero.",
+              basePosition
+            );
+          }
+          const now = self.now.getTime();
+          if (comparator === ">" || comparator === ">=") {
+            const end = new Date(now - durationMillis);
+            const start = new Date(0);
+            if (start.getTime() >= end.getTime()) {
+              return yield* self.fail(
+                "Age duration is larger than the available timeline.",
+                basePosition
+              );
+            }
+            yield* ensureNoUnknownOptions(options, self.input);
+            return {
+              _tag: "DateRange",
+              start: yield* self.asTimestamp(start, basePosition),
+              end: yield* self.asTimestamp(end, basePosition)
+            };
+          }
+          const start = new Date(now - durationMillis);
+          const end = self.now;
+          if (start.getTime() >= end.getTime()) {
+            return yield* self.fail(
+              "Age duration is larger than the available timeline.",
+              basePosition
+            );
+          }
+          yield* ensureNoUnknownOptions(options, self.input);
+          return {
+            _tag: "DateRange",
+            start: yield* self.asTimestamp(start, basePosition),
+            end: yield* self.asTimestamp(end, basePosition)
+          };
+        }
         case "links":
         case "validlinks":
         case "hasvalidlinks": {
@@ -1344,7 +1467,7 @@ class Parser {
           const unsupported = unsupportedFilterKeys.get(key);
           if (unsupported) {
             return yield* self.fail(
-              `Unknown filter type "${rawKey}". ${unsupported}`,
+              `Unknown filter type "${rawKey}". ${unsupported}${filterHelpHint}`,
               token.position
             );
           }
@@ -1353,7 +1476,7 @@ class Parser {
             ? formatSuggestionHint(suggestions)
             : ` Try "${defaultFilterExamples[0]}", "${defaultFilterExamples[1]}", or "${defaultFilterExamples[2]}".`;
           return yield* self.fail(
-            `Unknown filter type "${rawKey}".${hint}`,
+            `Unknown filter type "${rawKey}".${hint}${filterHelpHint}`,
             token.position
           );
         }
@@ -1365,6 +1488,17 @@ class Parser {
     return Effect.fail(failAt(this.input, position, message));
   }
 
+  private asTimestamp(
+    date: Date,
+    position: number
+  ): Effect.Effect<Timestamp, CliInputError> {
+    return Schema.decodeUnknown(Timestamp)(date).pipe(
+      Effect.mapError((error) =>
+        failAt(this.input, position, `Invalid timestamp: ${formatSchemaError(error)}`)
+      )
+    );
+  }
+
   private peek(): Token | undefined {
     return this.tokens[this.index];
   }
@@ -1405,7 +1539,8 @@ class Parser {
 export const parseFilterDsl = Effect.fn("FilterDsl.parse")((input: string) =>
   Effect.gen(function* () {
     const library = yield* FilterLibrary;
+    const nowMillis = yield* Clock.currentTimeMillis;
     const tokens = yield* tokenize(input);
-    return yield* new Parser(input, tokens, library).parse();
+    return yield* new Parser(input, tokens, library, new Date(nowMillis)).parse();
   })
 );

package/src/cli/filter-errors.ts

@@ -1,5 +1,5 @@
 import { ParseResult } from "effect";
-import { safeParseJson, issueDetails } from "./shared.js";
+import { safeParseJson, issueDetails, findJsonParseIssue, jsonParseTip } from "./parse-errors.js";
 import { formatAgentError, type AgentErrorPayload } from "./errors.js";
 
 const validFilterTags = [
@@ -31,6 +31,7 @@ const validFilterTags = [
 ];
 
 const filterDocs = "docs/filters/README.md";
+const filterHelpHint = "Tip: run \"skygent filter help\" for examples and aliases.";
 
 
 const getTag = (raw: string): string | undefined => {
@@ -48,13 +49,18 @@ const getTag = (raw: string): string | undefined => {
 const hasPath = (issue: { readonly path: ReadonlyArray<unknown> }, key: string) =>
   issue.path.length === 1 && issue.path[0] === key;
 
+const withHelpHint = (payload: Omit<AgentErrorPayload, "error">) => ({
+  ...payload,
+  details: payload.details ? [...payload.details, filterHelpHint] : [filterHelpHint]
+});
+
 const validationError = (
   payload: Omit<AgentErrorPayload, "error">
-) => formatAgentError({ error: "FilterValidationError", ...payload });
+) => formatAgentError({ error: "FilterValidationError", ...withHelpHint(payload) });
 
 const jsonParseError = (
   payload: Omit<AgentErrorPayload, "error">
-) => formatAgentError({ error: "FilterJsonParseError", ...payload });
+) => formatAgentError({ error: "FilterJsonParseError", ...withHelpHint(payload) });
 
 
 export const formatFilterParseError = (error: ParseResult.ParseError, raw: string): string => {
@@ -70,19 +76,15 @@ export const formatFilterParseError = (error: ParseResult.ParseError, raw: strin
   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 jsonParseError({
       message: "Invalid JSON in --filter-json.",
       received: raw,
       details: [
-        jsonParseIssue.message,
-        "Tip: wrap JSON in single quotes to avoid shell escaping issues."
+        jsonMessage,
+        jsonParseTip
       ]
     });
   }

package/src/cli/filter-help.ts

@@ -24,6 +24,7 @@ export const filterJsonDescription = (extra?: string) =>
     "Filter expression as JSON string.",
     "Sync/query filters run at ingestion or query time; store config filters are materialized views.",
     ...(extra ? [extra] : []),
+    "Tip: run \"skygent filter help\" for all predicates and aliases.",
     "",
     filterJsonExamples
   ].join("\n");
@@ -31,6 +32,7 @@ export const filterJsonDescription = (extra?: string) =>
 const filterDslExamples = [
   "Examples:",
   "  hashtag:#ai AND author:user.bsky.social",
+  "  from:alice.bsky.social",
   "  authorin:alice.bsky.social,bob.bsky.social",
   "  hashtagin:#tech,#coding",
   "  contains:\"typescript\",caseSensitive=false",
@@ -40,9 +42,13 @@ const filterDslExamples = [
   "  engagement:minLikes=100,minReplies=5",
   "  hasmedia",
   "  hasembed",
+  "  has:images",
   "  language:en,es",
   "  @tech AND author:user.bsky.social",
   "  date:2024-01-01T00:00:00Z..2024-01-31T00:00:00Z",
+  "  since:24h",
+  "  until:2024-01-15",
+  "  age:<72h",
   "  links:onError=exclude",
   "  trending:#ai,onError=include",
   "  (hashtag:#ai OR hashtag:#ml) AND author:user.bsky.social",
@@ -65,6 +71,7 @@ export const filterDslDescription = () =>
     "Options are comma-separated (no spaces); quote values with spaces.",
     "Lists use commas (e.g. authorin:alice,bob). Named filters use @name.",
     "Defaults: onError defaults to include for trending and exclude for links.",
+    "Tip: run \"skygent filter help\" for all predicates and aliases.",
     "",
     filterDslExamples
   ].join("\n");

package/src/cli/filter-input.ts

@@ -1,4 +1,5 @@
 import { Effect, Option } from "effect";
+import type { Clock as ClockService } from "effect/Clock";
 import { FilterExprSchema, all } from "../domain/filter.js";
 import type { FilterExpr } from "../domain/filter.js";
 import type { FilterLibrary } from "../services/filter-library.js";
@@ -16,7 +17,7 @@ const conflictError = (filter: boolean, filterJson: boolean) =>
 export const parseFilterExpr = (
   filter: Option.Option<string>,
   filterJson: Option.Option<string>
-): Effect.Effect<FilterExpr, CliInputError | CliJsonError, FilterLibrary> =>
+): Effect.Effect<FilterExpr, CliInputError | CliJsonError, FilterLibrary | ClockService> =>
   Option.match(filter, {
     onNone: () =>
       Option.match(filterJson, {
@@ -36,7 +37,7 @@ export const parseFilterExpr = (
 export const parseOptionalFilterExpr = (
   filter: Option.Option<string>,
   filterJson: Option.Option<string>
-): Effect.Effect<Option.Option<FilterExpr>, CliInputError | CliJsonError, FilterLibrary> =>
+): Effect.Effect<Option.Option<FilterExpr>, CliInputError | CliJsonError, FilterLibrary | ClockService> =>
   Option.match(filter, {
     onNone: () =>
       Option.match(filterJson, {