@mepuka/skygent 0.2.0

package/src/cli/filter-errors.ts

@@ -0,0 +1,208 @@
+import { ParseResult } from "effect";
+import { safeParseJson, issueDetails } from "./shared.js";
+import { formatAgentError, type AgentErrorPayload } from "./errors.js";
+
+const validFilterTags = [
+  "All",
+  "None",
+  "And",
+  "Or",
+  "Not",
+  "Author",
+  "Hashtag",
+  "AuthorIn",
+  "HashtagIn",
+  "Contains",
+  "IsReply",
+  "IsQuote",
+  "IsRepost",
+  "IsOriginal",
+  "Engagement",
+  "HasImages",
+  "HasVideo",
+  "HasLinks",
+  "HasMedia",
+  "HasEmbed",
+  "Language",
+  "Regex",
+  "DateRange",
+  "HasValidLinks",
+  "Trending"
+];
+
+const filterDocs = "docs/filters/README.md";
+
+
+const getTag = (raw: string): string | undefined => {
+  const parsed = safeParseJson(raw);
+  if (!parsed || typeof parsed !== "object") {
+    return undefined;
+  }
+  if (!("_tag" in parsed)) {
+    return undefined;
+  }
+  const tag = (parsed as { readonly _tag?: unknown })._tag;
+  return typeof tag === "string" ? tag : undefined;
+};
+
+const hasPath = (issue: { readonly path: ReadonlyArray<unknown> }, key: string) =>
+  issue.path.length === 1 && issue.path[0] === key;
+
+const validationError = (
+  payload: Omit<AgentErrorPayload, "error">
+) => formatAgentError({ error: "FilterValidationError", ...payload });
+
+const jsonParseError = (
+  payload: Omit<AgentErrorPayload, "error">
+) => formatAgentError({ error: "FilterJsonParseError", ...payload });
+
+
+export const formatFilterParseError = (error: ParseResult.ParseError, raw: string): string => {
+  const issues = ParseResult.ArrayFormatter.formatErrorSync(error);
+  if (issues.length === 0) {
+    return validationError({
+      message: "Filter expression failed validation.",
+      details: [ParseResult.TreeFormatter.formatErrorSync(error)]
+    });
+  }
+
+  const tag = getTag(raw);
+  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")
+  );
+  if (jsonParseIssue) {
+    return jsonParseError({
+      message: "Invalid JSON in --filter-json.",
+      received: raw,
+      details: [
+        jsonParseIssue.message,
+        "Tip: wrap JSON in single quotes to avoid shell escaping issues."
+      ]
+    });
+  }
+
+  const tagMissing = issues.some((issue) => issue._tag === "Missing" && hasPath(issue, "_tag"));
+  if (tagMissing) {
+    return validationError({
+      message: "Filter expression requires a _tag field.",
+      received: receivedValue,
+      expected: { _tag: "Hashtag", tag: "#ai" },
+      fix:
+        "Add a valid _tag such as Hashtag, Author, Regex, or DateRange.",
+      details: [`See ${filterDocs} for filter examples.`],
+      validTags: validFilterTags
+    });
+  }
+
+  const tagInvalid = issues.some((issue) => issue._tag === "Type" && hasPath(issue, "_tag"));
+  if (tagInvalid) {
+    return validationError({
+      message: `Invalid filter type${tag ? ` "${tag}"` : ""}.`,
+      received: receivedValue,
+      expected: { _tag: "Hashtag", tag: "#ai" },
+      fix: "Use a valid filter _tag.",
+      details: [`See ${filterDocs} for the full list of filters.`],
+      validTags: validFilterTags
+    });
+  }
+
+  if (tag === "Regex" && issues.some((issue) => hasPath(issue, "patterns"))) {
+    const hasPatternField =
+      received && typeof received === "object" && "pattern" in received;
+    return validationError({
+      message: "Regex filter requires a patterns field (array of strings).",
+      received: receivedValue,
+      expected: { _tag: "Regex", patterns: ["[Tt]rump"], flags: "i" },
+      fix: hasPatternField
+        ? "Change 'pattern' to 'patterns' and wrap the value in an array."
+        : "Add a patterns array with at least one regex pattern."
+    });
+  }
+  if (tag === "AuthorIn" && issues.some((issue) => hasPath(issue, "handles"))) {
+    return validationError({
+      message: "AuthorIn filter requires a handles array.",
+      received: receivedValue,
+      expected: { _tag: "AuthorIn", handles: ["alice.bsky.social", "bob.bsky.social"] },
+      fix: "Provide at least one handle in handles."
+    });
+  }
+  if (tag === "HashtagIn" && issues.some((issue) => hasPath(issue, "tags"))) {
+    return validationError({
+      message: "HashtagIn filter requires a tags array.",
+      received: receivedValue,
+      expected: { _tag: "HashtagIn", tags: ["#tech", "#coding"] },
+      fix: "Provide at least one hashtag in tags."
+    });
+  }
+  if (tag === "Contains" && issues.some((issue) => hasPath(issue, "text"))) {
+    return validationError({
+      message: "Contains filter requires a text string.",
+      received: receivedValue,
+      expected: { _tag: "Contains", text: "typescript", caseSensitive: false },
+      fix: "Provide a non-empty text value to search for."
+    });
+  }
+  if (tag === "Hashtag" && issues.some((issue) => hasPath(issue, "tag"))) {
+    return validationError({
+      message: "Hashtag filter requires a tag field.",
+      received: receivedValue,
+      expected: { _tag: "Hashtag", tag: "#ai" },
+      fix: "Add tag with a leading #, e.g. #ai."
+    });
+  }
+  if (tag === "Author" && issues.some((issue) => hasPath(issue, "handle"))) {
+    return validationError({
+      message: "Author filter requires a handle field.",
+      received: receivedValue,
+      expected: { _tag: "Author", handle: "user.bsky.social" },
+      fix: "Add handle with the full Bluesky handle."
+    });
+  }
+  if (tag === "DateRange" && issues.some((issue) => hasPath(issue, "start") || hasPath(issue, "end"))) {
+    return validationError({
+      message: "DateRange filter requires start and end ISO timestamps with timezone.",
+      received: receivedValue,
+      expected: {
+        _tag: "DateRange",
+        start: "2026-01-01T00:00:00Z",
+        end: "2026-01-31T23:59:59Z"
+      },
+      fix: "Provide ISO timestamps for start and end with timezone (e.g. Z).",
+      details: [`See ${filterDocs} for range examples.`]
+    });
+  }
+  if (tag === "Language" && issues.some((issue) => hasPath(issue, "langs"))) {
+    return validationError({
+      message: "Language filter requires a langs array.",
+      received: receivedValue,
+      expected: { _tag: "Language", langs: ["en", "es"] },
+      fix: "Provide one or more language codes in langs."
+    });
+  }
+  if (
+    (tag === "HasValidLinks" || tag === "Trending") &&
+    issues.some((issue) => hasPath(issue, "onError"))
+  ) {
+    return validationError({
+      message: "Effectful filters require an onError policy.",
+      received: receivedValue,
+      expected: {
+        _tag: tag,
+        onError: { _tag: "Retry", maxRetries: 3, baseDelay: "1 second" }
+      },
+      fix: "Add an onError policy (Include, Exclude, or Retry with maxRetries/baseDelay)."
+    });
+  }
+
+  return validationError({
+    message: "Filter expression failed validation.",
+    received: receivedValue,
+    details: issueDetails(issues)
+  });
+};

package/src/cli/filter-help.ts

@@ -0,0 +1,70 @@
+const filterJsonExamples = [
+  "Examples:",
+  "  All posts:       '{\"_tag\":\"All\"}'",
+  "  By author:       '{\"_tag\":\"Author\",\"handle\":\"user.bsky.social\"}'",
+  "  By hashtag:      '{\"_tag\":\"Hashtag\",\"tag\":\"#ai\"}'",
+  "  Authors list:    '{\"_tag\":\"AuthorIn\",\"handles\":[\"alice.bsky.social\",\"bob.bsky.social\"]}'",
+  "  Tags list:       '{\"_tag\":\"HashtagIn\",\"tags\":[\"#tech\",\"#coding\"]}'",
+  "  Contains text:   '{\"_tag\":\"Contains\",\"text\":\"typescript\",\"caseSensitive\":false}'",
+  "  Is reply:        '{\"_tag\":\"IsReply\"}'",
+  "  Engagement:      '{\"_tag\":\"Engagement\",\"minLikes\":100}'",
+  "  Has media:       '{\"_tag\":\"HasMedia\"}'",
+  "  Has embed:       '{\"_tag\":\"HasEmbed\"}'",
+  "  Language:        '{\"_tag\":\"Language\",\"langs\":[\"en\",\"es\"]}'",
+  "  By regex:        '{\"_tag\":\"Regex\",\"patterns\":[\"pattern\"],\"flags\":\"i\"}'",
+  "  Trending tag:    '{\"_tag\":\"Trending\",\"tag\":\"#ai\",\"onError\":{\"_tag\":\"Include\"}}'",
+  "  Valid links:     '{\"_tag\":\"HasValidLinks\",\"onError\":{\"_tag\":\"Exclude\"}}'",
+  "  Combined (AND):  '{\"_tag\":\"And\",\"left\":{...},\"right\":{...}}'",
+  "  Combined (OR):   '{\"_tag\":\"Or\",\"left\":{...},\"right\":{...}}'",
+  "  Inverted (NOT):  '{\"_tag\":\"Not\",\"expr\":{...}}'"
+].join("\n");
+
+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] : []),
+    "",
+    filterJsonExamples
+  ].join("\n");
+
+const filterDslExamples = [
+  "Examples:",
+  "  hashtag:#ai AND author:user.bsky.social",
+  "  authorin:alice.bsky.social,bob.bsky.social",
+  "  hashtagin:#tech,#coding",
+  "  contains:\"typescript\",caseSensitive=false",
+  "  NOT hashtag:#spam",
+  "  regex:/pattern/i",
+  "  is:reply",
+  "  engagement:minLikes=100,minReplies=5",
+  "  hasmedia",
+  "  hasembed",
+  "  language:en,es",
+  "  @tech AND author:user.bsky.social",
+  "  date:2024-01-01T00:00:00Z..2024-01-31T00:00:00Z",
+  "  links:onError=exclude",
+  "  trending:#ai,onError=include",
+  "  (hashtag:#ai OR hashtag:#ml) AND author:user.bsky.social",
+  "",
+  "Aliases:",
+  "  from:alice.bsky.social        -> author:alice.bsky.social",
+  "  tag:#ai                       -> hashtag:#ai",
+  "  text:\"hello\"                 -> contains:\"hello\"",
+  "  lang:en                       -> language:en",
+  "  authors:alice,bob             -> authorin:alice,bob",
+  "  tags:#ai,#ml                  -> hashtagin:#ai,#ml",
+  "  is:reply|quote|repost|original",
+  "  has:images|video|links|media|embed"
+].join("\n");
+
+export const filterDslDescription = () =>
+  [
+    "Filter expression using the DSL.",
+    "Sync/query filters run at ingestion or query time; store config filters are materialized views.",
+    "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.",
+    "",
+    filterDslExamples
+  ].join("\n");

package/src/cli/filter-input.ts

@@ -0,0 +1,54 @@
+import { Effect, Option } from "effect";
+import { FilterExprSchema, all } from "../domain/filter.js";
+import type { FilterExpr } from "../domain/filter.js";
+import type { FilterLibrary } from "../services/filter-library.js";
+import { CliInputError, CliJsonError } from "./errors.js";
+import { decodeJson } from "./parse.js";
+import { formatFilterParseError } from "./filter-errors.js";
+import { parseFilterDsl } from "./filter-dsl.js";
+
+const conflictError = (filter: boolean, filterJson: boolean) =>
+  CliInputError.make({
+    message: "Use only one of --filter or --filter-json.",
+    cause: { filter, filterJson }
+  });
+
+export const parseFilterExpr = (
+  filter: Option.Option<string>,
+  filterJson: Option.Option<string>
+): Effect.Effect<FilterExpr, CliInputError | CliJsonError, FilterLibrary> =>
+  Option.match(filter, {
+    onNone: () =>
+      Option.match(filterJson, {
+        onNone: () => Effect.succeed(all()),
+        onSome: (raw) =>
+          decodeJson(FilterExprSchema, raw, {
+            formatter: formatFilterParseError
+          })
+      }),
+    onSome: (raw) =>
+      Option.match(filterJson, {
+        onNone: () => parseFilterDsl(raw),
+        onSome: () => Effect.fail(conflictError(true, true))
+      })
+  });
+
+export const parseOptionalFilterExpr = (
+  filter: Option.Option<string>,
+  filterJson: Option.Option<string>
+): Effect.Effect<Option.Option<FilterExpr>, CliInputError | CliJsonError, FilterLibrary> =>
+  Option.match(filter, {
+    onNone: () =>
+      Option.match(filterJson, {
+        onNone: () => Effect.succeed(Option.none()),
+        onSome: (raw) =>
+          decodeJson(FilterExprSchema, raw, {
+            formatter: formatFilterParseError
+          }).pipe(Effect.map(Option.some))
+      }),
+    onSome: (raw) =>
+      Option.match(filterJson, {
+        onNone: () => parseFilterDsl(raw).pipe(Effect.map(Option.some)),
+        onSome: () => Effect.fail(conflictError(true, true))
+      })
+  });