@mepuka/skygent 0.2.0 → 0.3.0

package/src/cli/graph.ts

@@ -3,13 +3,23 @@ import { Effect, Option, Stream } from "effect";
 import { BskyClient } from "../services/bsky-client.js";
 import { AppConfigService } from "../services/app-config.js";
 import { IdentityResolver } from "../services/identity-resolver.js";
-import type { ListItemView, ListView, ProfileView, RelationshipView } from "../domain/bsky.js";
-import { decodeActor, parseLimit } from "./shared-options.js";
+import { ProfileResolver } from "../services/profile-resolver.js";
+import type { ListItemView, ListView } from "../domain/bsky.js";
+import { decodeActor } from "./shared-options.js";
 import { CliInputError } from "./errors.js";
 import { withExamples } from "./help.js";
 import { writeJson, writeJsonStream, writeText } from "./output.js";
 import { renderTableLegacy } from "./doc/table.js";
-import { jsonNdjsonTableFormats, resolveOutputFormat } from "./output-format.js";
+import { renderProfileTable } from "./doc/table-renderers.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 {
+  buildRelationshipGraph,
+  relationshipEntries,
+  type RelationshipEntry,
+  type RelationshipNode
+} from "../graph/relationships.js";
 
 const actorArg = Args.text({ name: "actor" }).pipe(
   Args.withDescription("Bluesky handle or DID")
@@ -19,14 +29,12 @@ const listUriArg = Args.text({ name: "uri" }).pipe(
   Args.withDescription("Bluesky list URI (at://...)")
 );
 
-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(
@@ -42,19 +50,9 @@ const purposeOption = Options.choice("purpose", ["modlist", "curatelist"]).pipe(
 const othersOption = Options.text("others").pipe(
   Options.withDescription("Comma-separated list of actors to compare" )
 );
-
-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 rawOption = Options.boolean("raw").pipe(
+  Options.withDescription("Output raw relationship data (no wrapper fields)")
+);
 
 const renderListTable = (
   lists: ReadonlyArray<ListView>,
@@ -71,35 +69,33 @@ const renderListTable = (
   return cursor ? `${table}\n\nCursor: ${cursor}` : table;
 };
 
-const renderRelationshipsTable = (relationships: ReadonlyArray<RelationshipView>) => {
-  const rows = relationships.map((rel) => {
-    if ("notFound" in rel && rel.notFound) {
-      return [String(rel.actor), "not-found", "", "", "", "", ""];
-    }
-    const relationship = rel as RelationshipView & {
-      did: string;
-      following?: string;
-      followedBy?: string;
-      blocking?: string;
-      blockedBy?: string;
-      blockingByList?: string;
-      blockedByList?: string;
-    };
+const renderRelationshipsTable = (entries: ReadonlyArray<RelationshipEntry>) => {
+  const rows = entries.map((entry) => {
+    const otherInputs = entry.other.inputs.join(", ");
+    const handle = entry.other.handle ?? "";
+    const did = entry.other.did ?? (entry.other.notFound ? "not-found" : "");
+    const rel = entry.relationship;
     return [
-      relationship.did,
-      relationship.following ? "yes" : "",
-      relationship.followedBy ? "yes" : "",
-      relationship.blocking ? "yes" : "",
-      relationship.blockedBy ? "yes" : "",
-      relationship.blockingByList ? "yes" : "",
-      relationship.blockedByList ? "yes" : ""
+      otherInputs,
+      handle,
+      did,
+      rel.following ? "yes" : "",
+      rel.followedBy ? "yes" : "",
+      rel.mutual ? "yes" : "",
+      rel.blocking ? "yes" : "",
+      rel.blockedBy ? "yes" : "",
+      rel.blockingByList ? "yes" : "",
+      rel.blockedByList ? "yes" : ""
     ];
   });
   return renderTableLegacy(
     [
+      "INPUTS",
+      "HANDLE",
       "DID",
       "FOLLOWING",
       "FOLLOWED BY",
+      "MUTUAL",
       "BLOCKING",
       "BLOCKED BY",
       "BLOCK BY LIST",
@@ -127,27 +123,23 @@ const followersCommand = Command.make(
       const appConfig = yield* AppConfigService;
       const client = yield* BskyClient;
       const resolvedActor = yield* decodeActor(actor);
-      const parsedLimit = yield* parseLimit(limit);
+      const { limit: limitValue, cursor: cursorValue } = yield* parsePagination(limit, cursor);
       const options = {
-        ...(Option.isSome(parsedLimit) ? { limit: parsedLimit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {})
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {})
       };
       const result = yield* client.getFollowers(resolvedActor, options);
-      const outputFormat = resolveOutputFormat(
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson: writeJsonStream(Stream.fromIterable(result.followers)),
+          table: writeText(renderProfileTable(result.followers, result.cursor))
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.followers));
-        return;
-      }
-      if (outputFormat === "table") {
-        yield* writeText(renderProfileTable(result.followers, result.cursor));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -166,27 +158,23 @@ const followsCommand = Command.make(
       const appConfig = yield* AppConfigService;
       const client = yield* BskyClient;
       const resolvedActor = yield* decodeActor(actor);
-      const parsedLimit = yield* parseLimit(limit);
+      const { limit: limitValue, cursor: cursorValue } = yield* parsePagination(limit, cursor);
       const options = {
-        ...(Option.isSome(parsedLimit) ? { limit: parsedLimit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {})
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {})
       };
       const result = yield* client.getFollows(resolvedActor, options);
-      const outputFormat = resolveOutputFormat(
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson: writeJsonStream(Stream.fromIterable(result.follows)),
+          table: writeText(renderProfileTable(result.follows, result.cursor))
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.follows));
-        return;
-      }
-      if (outputFormat === "table") {
-        yield* writeText(renderProfileTable(result.follows, result.cursor));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -205,27 +193,23 @@ const knownFollowersCommand = Command.make(
       const appConfig = yield* AppConfigService;
       const client = yield* BskyClient;
       const resolvedActor = yield* decodeActor(actor);
-      const parsedLimit = yield* parseLimit(limit);
+      const { limit: limitValue, cursor: cursorValue } = yield* parsePagination(limit, cursor);
       const options = {
-        ...(Option.isSome(parsedLimit) ? { limit: parsedLimit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {})
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {})
       };
       const result = yield* client.getKnownFollowers(resolvedActor, options);
-      const outputFormat = resolveOutputFormat(
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson: writeJsonStream(Stream.fromIterable(result.followers)),
+          table: writeText(renderProfileTable(result.followers, result.cursor))
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.followers));
-        return;
-      }
-      if (outputFormat === "table") {
-        yield* writeText(renderProfileTable(result.followers, result.cursor));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -237,12 +221,13 @@ const knownFollowersCommand = Command.make(
 
 const relationshipsCommand = Command.make(
   "relationships",
-  { actor: actorArg, others: othersOption, format: formatOption },
-  ({ actor, others, format }) =>
+  { actor: actorArg, others: othersOption, format: formatOption, raw: rawOption },
+  ({ actor, others, format, raw }) =>
     Effect.gen(function* () {
       const appConfig = yield* AppConfigService;
       const client = yield* BskyClient;
       const identities = yield* IdentityResolver;
+      const profiles = yield* ProfileResolver;
       const resolveDid = (value: string) =>
         Effect.gen(function* () {
           const decoded = yield* decodeActor(value);
@@ -274,22 +259,84 @@ const relationshipsCommand = Command.make(
         (value) => resolveDid(value),
         { concurrency: "unbounded" }
       );
+      const didToInputs = new Map<string, Array<string>>();
+      resolvedOthers.forEach((did, index) => {
+        const input = uniqueOthers[index];
+        if (input) {
+          const existing = didToInputs.get(did);
+          if (existing) {
+            existing.push(input);
+          } else {
+            didToInputs.set(did, [input]);
+          }
+        }
+      });
       const result = yield* client.getRelationships(resolvedActor, resolvedOthers);
-      const outputFormat = resolveOutputFormat(
+      const handleFromInputs = (inputs: ReadonlyArray<string>) =>
+        inputs.find((input) => !input.startsWith("did:"));
+      const inputsForActor = [actor];
+      const didsNeedingHandle = [resolvedActor, ...resolvedOthers].filter((did) => {
+        const inputs = did === resolvedActor ? inputsForActor : didToInputs.get(did) ?? [];
+        return handleFromInputs(inputs) === undefined;
+      });
+      const handles = yield* Effect.forEach(
+        didsNeedingHandle,
+        (did) =>
+          profiles.handleForDid(did).pipe(
+            Effect.either,
+            Effect.map((result) => [did, result] as const)
+          ),
+        { concurrency: "unbounded" }
+      );
+      const handleMap = new Map<string, string>();
+      for (const [did, result] of handles) {
+        if (result._tag === "Right") {
+          handleMap.set(did, String(result.right));
+        }
+      }
+      const buildNode = (
+        did: string,
+        inputs: ReadonlyArray<string>,
+        handle?: string
+      ): RelationshipNode => ({
+        did,
+        inputs,
+        ...(handle ? { handle } : {})
+      });
+      const actorHandle = handleFromInputs(inputsForActor) ?? handleMap.get(resolvedActor);
+      const nodesByKey = new Map<string, RelationshipNode>();
+      nodesByKey.set(resolvedActor, buildNode(resolvedActor, inputsForActor, actorHandle));
+      for (const [did, inputs] of didToInputs.entries()) {
+        const handle = handleFromInputs(inputs) ?? handleMap.get(did);
+        nodesByKey.set(did, buildNode(did, inputs, handle));
+      }
+      const graphResult = buildRelationshipGraph(
+        resolvedActor,
+        nodesByKey,
+        result.relationships
+      );
+      const entries = relationshipEntries(graphResult.graph);
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: raw
+            ? writeJson(result)
+            : writeJson({
+                actor: nodesByKey.get(resolvedActor) ?? {
+                  did: resolvedActor,
+                  inputs: [actor]
+                },
+                relationships: entries
+              }),
+          ndjson: raw
+            ? writeJsonStream(Stream.fromIterable(result.relationships))
+            : writeJsonStream(Stream.fromIterable(entries)),
+          table: writeText(renderRelationshipsTable(entries))
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.relationships));
-        return;
-      }
-      if (outputFormat === "table") {
-        yield* writeText(renderRelationshipsTable(result.relationships));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -307,28 +354,24 @@ const listsCommand = Command.make(
       const appConfig = yield* AppConfigService;
       const client = yield* BskyClient;
       const resolvedActor = yield* decodeActor(actor);
-      const parsedLimit = yield* parseLimit(limit);
+      const { limit: limitValue, cursor: cursorValue } = yield* parsePagination(limit, cursor);
       const options = {
-        ...(Option.isSome(parsedLimit) ? { limit: parsedLimit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {}),
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {}),
         ...(Option.isSome(purpose) ? { purposes: [purpose.value] } : {})
       };
       const result = yield* client.getLists(resolvedActor, options);
-      const outputFormat = resolveOutputFormat(
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson: writeJsonStream(Stream.fromIterable(result.lists)),
+          table: writeText(renderListTable(result.lists, result.cursor))
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.lists));
-        return;
-      }
-      if (outputFormat === "table") {
-        yield* writeText(renderListTable(result.lists, result.cursor));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -346,29 +389,25 @@ const listCommand = Command.make(
     Effect.gen(function* () {
       const appConfig = yield* AppConfigService;
       const client = yield* BskyClient;
-      const parsedLimit = yield* parseLimit(limit);
+      const { limit: limitValue, cursor: cursorValue } = yield* parsePagination(limit, cursor);
       const options = {
-        ...(Option.isSome(parsedLimit) ? { limit: parsedLimit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {})
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {})
       };
       const result = yield* client.getList(uri, options);
-      const outputFormat = resolveOutputFormat(
+      const header = `${result.list.name} (${result.list.purpose}) by ${result.list.creator.handle}`;
+      const body = renderListItemsTable(result.items, result.cursor);
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson: writeJsonStream(Stream.fromIterable(result.items)),
+          table: writeText(`${header}\n\n${body}`)
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.items));
-        return;
-      }
-      if (outputFormat === "table") {
-        const header = `${result.list.name} (${result.list.purpose}) by ${result.list.creator.handle}`;
-        const body = renderListItemsTable(result.items, result.cursor);
-        yield* writeText(`${header}\n\n${body}`);
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -385,27 +424,26 @@ const blocksCommand = Command.make(
     Effect.gen(function* () {
       const appConfig = yield* AppConfigService;
       const client = yield* BskyClient;
-      const parsedLimit = yield* parseLimit(limit);
+      const { limit: limitValue, cursor: cursorValue } = yield* parsePagination(limit, cursor);
       const options = {
-        ...(Option.isSome(parsedLimit) ? { limit: parsedLimit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {})
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {})
       };
       const result = yield* client.getBlocks(options);
-      const outputFormat = resolveOutputFormat(
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson:
+            result.blocks.length === 0
+              ? writeText("[]")
+              : writeJsonStream(Stream.fromIterable(result.blocks)),
+          table: writeText(renderProfileTable(result.blocks, result.cursor))
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.blocks));
-        return;
-      }
-      if (outputFormat === "table") {
-        yield* writeText(renderProfileTable(result.blocks, result.cursor));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(
@@ -422,27 +460,26 @@ const mutesCommand = Command.make(
     Effect.gen(function* () {
       const appConfig = yield* AppConfigService;
       const client = yield* BskyClient;
-      const parsedLimit = yield* parseLimit(limit);
+      const { limit: limitValue, cursor: cursorValue } = yield* parsePagination(limit, cursor);
       const options = {
-        ...(Option.isSome(parsedLimit) ? { limit: parsedLimit.value } : {}),
-        ...(Option.isSome(cursor) ? { cursor: cursor.value } : {})
+        ...(limitValue !== undefined ? { limit: limitValue } : {}),
+        ...(cursorValue !== undefined ? { cursor: cursorValue } : {})
       };
       const result = yield* client.getMutes(options);
-      const outputFormat = resolveOutputFormat(
+      yield* emitWithFormat(
         format,
         appConfig.outputFormat,
         jsonNdjsonTableFormats,
-        "json"
+        "json",
+        {
+          json: writeJson(result),
+          ndjson:
+            result.mutes.length === 0
+              ? writeText("[]")
+              : writeJsonStream(Stream.fromIterable(result.mutes)),
+          table: writeText(renderProfileTable(result.mutes, result.cursor))
+        }
       );
-      if (outputFormat === "ndjson") {
-        yield* writeJsonStream(Stream.fromIterable(result.mutes));
-        return;
-      }
-      if (outputFormat === "table") {
-        yield* writeText(renderProfileTable(result.mutes, result.cursor));
-        return;
-      }
-      yield* writeJson(result);
     })
 ).pipe(
   Command.withDescription(

package/src/cli/input.ts

@@ -0,0 +1,45 @@
+import { SystemError, type PlatformError } from "@effect/platform/Error";
+import { Context, Effect, Layer, Stream } from "effect";
+import { createInterface } from "node:readline";
+
+export interface CliInputService {
+  readonly lines: Stream.Stream<string, PlatformError>;
+}
+
+const makeLines = () =>
+  Stream.unwrapScoped(
+    Effect.acquireRelease(
+      Effect.sync(() =>
+        createInterface({
+          input: process.stdin,
+          crlfDelay: Infinity
+        })
+      ),
+      (rl) => Effect.sync(() => rl.close())
+    ).pipe(
+      Effect.map((rl) =>
+        Stream.fromAsyncIterable(
+          rl,
+          (cause) =>
+            new SystemError({
+              module: "Stream",
+              method: "stdin",
+              reason: "Unknown",
+              cause
+            })
+        )
+      )
+    )
+  );
+
+export class CliInput extends Context.Tag("@skygent/CliInput")<
+  CliInput,
+  CliInputService
+>() {
+  static readonly layer = Layer.succeed(
+    CliInput,
+    CliInput.of({
+      lines: makeLines()
+    })
+  );
+}

package/src/cli/layers.ts

@@ -18,10 +18,12 @@ import { SyncCheckpointStore } from "../services/sync-checkpoint-store.js";
 import { SyncReporter } from "../services/sync-reporter.js";
 import { SyncSettings } from "../services/sync-settings.js";
 import { StoreCleaner } from "../services/store-cleaner.js";
+import { StoreRenamer } from "../services/store-renamer.js";
 import { LinkValidator } from "../services/link-validator.js";
 import { TrendingTopics } from "../services/trending-topics.js";
 import { ResourceMonitor } from "../services/resource-monitor.js";
 import { CliOutput } from "./output.js";
+import { CliInput } from "./input.js";
 import { DerivationEngine } from "../services/derivation-engine.js";
 import { DerivationValidator } from "../services/derivation-validator.js";
 import { DerivationSettings } from "../services/derivation-settings.js";
@@ -114,6 +116,12 @@ const viewCheckpointLayer = ViewCheckpointStore.layer.pipe(
 const lineageLayer = LineageStore.layer.pipe(
   Layer.provideMerge(storageLayer)
 );
+const storeRenamerLayer = StoreRenamer.layer.pipe(
+  Layer.provideMerge(appConfigLayer),
+  Layer.provideMerge(managerLayer),
+  Layer.provideMerge(storeDbLayer),
+  Layer.provideMerge(lineageLayer)
+);
 const compilerLayer = FilterCompiler.layer;
 const postParserLayer = PostParser.layer;
 const derivationEngineLayer = DerivationEngine.layer.pipe(
@@ -157,6 +165,7 @@ export const CliLive = Layer.mergeAll(
   appConfigLayer,
   filterSettingsLayer,
   credentialLayer,
+  CliInput.layer,
   CliOutput.layer,
   resourceMonitorLayer,
   managerLayer,
@@ -164,6 +173,7 @@ export const CliLive = Layer.mergeAll(
   indexLayer,
   eventLogLayer,
   cleanerLayer,
+  storeRenamerLayer,
   syncLayer,
   checkpointLayer,
   viewCheckpointLayer,

package/src/cli/logging.ts

@@ -132,5 +132,13 @@ export const makeSyncReporter = (
             { discard: true }
           );
         }
+      }).pipe(Effect.orElseSucceed(() => undefined)),
+    warn: (message, data) =>
+      Effect.gen(function* () {
+        const format = yield* resolveLogFormat;
+        yield* logEventWith(output, format, "WARN", {
+          message,
+          ...data
+        });
       }).pipe(Effect.orElseSucceed(() => undefined))
   });

package/src/cli/output-render.ts

@@ -0,0 +1,14 @@
+import { Effect, Option } from "effect";
+import type { OutputFormat } from "../domain/config.js";
+import { resolveOutputFormat } from "./output-format.js";
+
+export const emitWithFormat = <T extends string, E, R>(
+  format: Option.Option<T>,
+  configFormat: OutputFormat,
+  supported: readonly T[],
+  fallback: T,
+  handlers: { readonly [K in T]: Effect.Effect<unknown, E, R> }
+): Effect.Effect<unknown, E, R> => {
+  const resolved = resolveOutputFormat(format, configFormat, supported, fallback);
+  return handlers[resolved];
+};

package/src/cli/pagination.ts

@@ -0,0 +1,18 @@
+import { Options } from "@effect/cli";
+import { Effect, Option } from "effect";
+import { parseLimit } from "./shared-options.js";
+
+export const limitOption = Options.integer("limit").pipe(Options.optional);
+export const cursorOption = Options.text("cursor").pipe(Options.optional);
+
+export const parsePagination = (
+  limit: Option.Option<number>,
+  cursor: Option.Option<string>
+) =>
+  Effect.gen(function* () {
+    const parsedLimit = yield* parseLimit(limit);
+    return {
+      limit: Option.getOrUndefined(parsedLimit),
+      cursor: Option.getOrUndefined(cursor)
+    };
+  });

package/src/cli/parse-errors.ts

@@ -0,0 +1,18 @@
+/** 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}`;
+  });