@mepuka/skygent 0.2.0 → 0.3.1

package/src/cli/time.ts

@@ -0,0 +1,171 @@
+import { Duration, Effect, Schema } from "effect";
+import { Timestamp } from "../domain/primitives.js";
+import { CliInputError } from "./errors.js";
+
+export type TimeParseError = (message: string, cause?: unknown) => CliInputError;
+
+type TimeParseOptions = {
+  readonly label?: string;
+  readonly onError?: TimeParseError;
+};
+
+const defaultError: TimeParseError = (message, cause) =>
+  CliInputError.make({ message, cause });
+
+const compactDurationPattern = /^(-?\d+(?:\.\d+)?)(ms|s|m|h|d|w)$/i;
+const compactDurationUnits: Record<string, number> = {
+  ms: 1,
+  s: 1000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+  w: 604_800_000
+};
+
+const parseCompactDurationMillis = (raw: string): number | undefined => {
+  const match = raw.match(compactDurationPattern);
+  if (!match) {
+    return undefined;
+  }
+  const value = Number.parseFloat(match[1] ?? "");
+  const unit = (match[2] ?? "").toLowerCase();
+  const multiplier = compactDurationUnits[unit];
+  if (!Number.isFinite(value) || multiplier === undefined) {
+    return Number.NaN;
+  }
+  return value * multiplier;
+};
+
+const toUtcStartOfDay = (date: Date) =>
+  new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+
+const parseDateOnly = (raw: string): Date | undefined => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(raw);
+  if (!match) {
+    return undefined;
+  }
+  const year = Number.parseInt(match[1] ?? "", 10);
+  const month = Number.parseInt(match[2] ?? "", 10);
+  const day = Number.parseInt(match[3] ?? "", 10);
+  if (!Number.isFinite(year) || !Number.isFinite(month) || !Number.isFinite(day)) {
+    return undefined;
+  }
+  const date = new Date(Date.UTC(year, month - 1, day));
+  if (
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day
+  ) {
+    return undefined;
+  }
+  return date;
+};
+
+const looksLikeDate = (raw: string) => /^\d{4}-\d{2}-\d{2}/.test(raw);
+
+const hasExplicitTimezone = (raw: string) => /([zZ]|[+-]\d{2}:\d{2})$/.test(raw);
+
+const makeErrorFactory = (options?: TimeParseOptions): TimeParseError => {
+  const base = options?.onError ?? defaultError;
+  const label = options?.label;
+  if (!label) {
+    return base;
+  }
+  return (message, cause) => base(`${label}: ${message}`, cause);
+};
+
+export const parseDurationInput = (
+  raw: string,
+  options?: TimeParseOptions
+): Effect.Effect<Duration.Duration, CliInputError> =>
+  Effect.suspend(() => {
+    const onError = makeErrorFactory(options);
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+      return Effect.fail(onError("Duration cannot be empty."));
+    }
+
+    const compactMillis = parseCompactDurationMillis(trimmed);
+    if (compactMillis !== undefined) {
+      if (!Number.isFinite(compactMillis)) {
+        return Effect.fail(onError("Duration must be a finite number."));
+      }
+      if (compactMillis < 0) {
+        return Effect.fail(onError("Duration must be non-negative."));
+      }
+      return Effect.succeed(Duration.millis(compactMillis));
+    }
+
+    return Effect.try({
+      try: () => Duration.decode(trimmed as Duration.DurationInput),
+      catch: (cause) =>
+        onError(
+          `Invalid duration "${raw}". Use formats like "30 seconds", "500 millis", or "1.5h".`,
+          cause
+        )
+    }).pipe(
+      Effect.flatMap((duration) => {
+        if (!Duration.isFinite(duration)) {
+          return Effect.fail(onError("Duration must be finite."));
+        }
+        if (Duration.toMillis(duration) < 0) {
+          return Effect.fail(onError("Duration must be non-negative."));
+        }
+        return Effect.succeed(duration);
+      })
+    );
+  });
+
+export const parseTimeInput = (
+  raw: string,
+  now: Date,
+  options?: TimeParseOptions
+): Effect.Effect<Date, CliInputError> =>
+  Effect.suspend(() => {
+    const onError = makeErrorFactory(options);
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+      return Effect.fail(onError("Time value cannot be empty."));
+    }
+
+    const lower = trimmed.toLowerCase();
+    if (lower === "now") {
+      return Effect.succeed(new Date(now.getTime()));
+    }
+    if (lower === "today") {
+      return Effect.succeed(toUtcStartOfDay(now));
+    }
+    if (lower === "yesterday") {
+      return Effect.succeed(new Date(toUtcStartOfDay(now).getTime() - 86_400_000));
+    }
+
+    const dateOnly = parseDateOnly(trimmed);
+    if (dateOnly) {
+      return Effect.succeed(dateOnly);
+    }
+
+    if (looksLikeDate(trimmed)) {
+      if (/[Tt]/.test(trimmed) && !hasExplicitTimezone(trimmed)) {
+        return Effect.fail(
+          onError(
+            "Timestamp must include a timezone (e.g. 2026-01-01T00:00:00Z)."
+          )
+        );
+      }
+      return Schema.decodeUnknown(Timestamp)(trimmed).pipe(
+        Effect.mapError((cause) =>
+          onError(
+            `Invalid timestamp "${raw}". Expected ISO 8601 with timezone (e.g. 2026-01-01T00:00:00Z).`,
+            cause
+          )
+        )
+      );
+    }
+
+    return parseDurationInput(trimmed, options).pipe(
+      Effect.map((duration) => {
+        const millis = Duration.toMillis(duration);
+        return new Date(now.getTime() - millis);
+      })
+    );
+  });

package/src/cli/view-thread.ts

@@ -1,5 +1,5 @@
 import { Args, Command, Options } from "@effect/cli";
-import { Chunk, Console, Effect, Option, Schema, Stream } from "effect";
+import { Chunk, Console, Effect, Option, Stream } from "effect";
 import { PostUri, StoreName } from "../domain/primitives.js";
 import type { Post } from "../domain/post.js";
 import { all } from "../domain/filter.js";
@@ -11,15 +11,20 @@ import { StoreIndex } from "../services/store-index.js";
 import { SyncEngine } from "../services/sync-engine.js";
 import { renderThread } from "./doc/thread.js";
 import { renderPlain, renderAnsi } from "./doc/render.js";
-import { writeJson, writeText } from "./output.js";
+import { CliOutput, writeJson, writeText } from "./output.js";
 import { storeOptions } from "./store.js";
 import { withExamples } from "./help.js";
 import { CliInputError } from "./errors.js";
-import { formatSchemaError } from "./shared.js";
-import { parseBoundedIntOption } from "./shared-options.js";
+import {
+  depthOption as threadDepthOption,
+  parentHeightOption as threadParentHeightOption,
+  parseThreadDepth
+} from "./thread-options.js";
 import { textJsonFormats } from "./output-format.js";
+import { PositiveInt } from "./option-schemas.js";
 
 const uriArg = Args.text({ name: "uri" }).pipe(
+  Args.withSchema(PostUri),
   Args.withDescription("AT-URI of any post in the thread")
 );
 
@@ -38,6 +43,7 @@ const ansiOption = Options.boolean("ansi").pipe(
 );
 
 const widthOption = Options.integer("width").pipe(
+  Options.withSchema(PositiveInt),
   Options.withDescription("Line width for terminal output"),
   Options.optional
 );
@@ -47,14 +53,9 @@ const formatOption = Options.choice("format", textJsonFormats).pipe(
   Options.optional
 );
 
-const depthOption = Options.integer("depth").pipe(
-  Options.withDescription("Reply depth (API only, default: 6)"),
-  Options.optional
-);
-
-const parentHeightOption = Options.integer("parent-height").pipe(
-  Options.withDescription("Parent height (API only, default: 80)"),
-  Options.optional
+const depthOption = threadDepthOption("Reply depth (API only, default: 6)");
+const parentHeightOption = threadParentHeightOption(
+  "Parent height (API only, default: 80)"
 );
 
 export const threadCommand = Command.make(
@@ -71,32 +72,28 @@ export const threadCommand = Command.make(
   },
   ({ uri, store, compact, ansi, width, format, depth, parentHeight }) =>
     Effect.gen(function* () {
+      const output = yield* CliOutput;
       const outputFormat = Option.getOrElse(format, () => "text" as const);
       const w = Option.getOrUndefined(width);
-      const parsedDepth = yield* parseBoundedIntOption(depth, "depth", 0, 1000);
-      const parsedParentHeight = yield* parseBoundedIntOption(
-        parentHeight,
-        "parent-height",
-        0,
-        1000
-      );
-      const d = Option.getOrElse(parsedDepth, () => 6);
-      const ph = Option.getOrElse(parsedParentHeight, () => 80);
+      const { depth: depthValue, parentHeight: parentHeightValue } =
+        parseThreadDepth(depth, parentHeight);
+      const d = depthValue ?? 6;
+      const ph = parentHeightValue ?? 80;
 
       let posts: ReadonlyArray<Post>;
 
       if (Option.isSome(store)) {
         const index = yield* StoreIndex;
         const storeRef = yield* storeOptions.loadStoreRef(store.value);
-        const targetUri = yield* Schema.decodeUnknown(PostUri)(uri).pipe(
-          Effect.mapError((error) =>
-            CliInputError.make({
-              message: `Invalid post URI: ${formatSchemaError(error)}`,
-              cause: error
-            })
-          )
-        );
-        const hasTarget = yield* index.hasUri(storeRef, targetUri);
+        const totalPosts = yield* index.count(storeRef);
+        if (totalPosts > 20000) {
+          yield* output
+            .writeStderr(
+              `ℹ️  Store ${storeRef.name} has ${totalPosts} posts. Thread rendering will load all posts into memory.`
+            )
+            .pipe(Effect.catchAll(() => Effect.void));
+        }
+        const hasTarget = yield* index.hasUri(storeRef, uri);
         if (!hasTarget) {
           const engine = yield* SyncEngine;
           const source = DataSource.thread(uri, { depth: d, parentHeight: ph });
@@ -106,7 +103,7 @@ export const threadCommand = Command.make(
         const stream = index.query(storeRef, query);
         const collected = yield* Stream.runCollect(stream);
         const allPosts = Chunk.toReadonlyArray(collected);
-        const threadPosts = selectThreadPosts(allPosts, String(targetUri));
+        const threadPosts = selectThreadPosts(allPosts, String(uri));
         if (threadPosts.length === 0) {
           return yield* CliInputError.make({
             message: `Thread not found for ${uri}.`,
@@ -114,7 +111,7 @@ export const threadCommand = Command.make(
           });
         }
         // B1: Hint when only root post exists in store
-        if (threadPosts.length === 1 && threadPosts[0]?.uri === targetUri) {
+        if (threadPosts.length === 1 && threadPosts[0]?.uri === uri) {
           yield* Console.log("\nℹ️  Only root post found in store. Use --no-store to fetch full thread from API.\n");
         }
         posts = threadPosts;

package/src/cli/watch.ts

@@ -13,6 +13,7 @@ import { ResourceMonitor } from "../services/resource-monitor.js";
 import { withExamples } from "./help.js";
 import { buildJetstreamSelection, jetstreamOptions } from "./jetstream.js";
 import { makeWatchCommandBody } from "./sync-factory.js";
+import { parseOptionalDuration } from "./interval.js";
 import {
   feedUriArg,
   listUriArg,
@@ -25,29 +26,41 @@ import {
   postFilterJsonOption,
   authorFilterOption,
   includePinsOption,
-  decodeActor,
   quietOption,
   refreshOption,
   strictOption,
-  maxErrorsOption,
-  parseMaxErrors,
-  parseBoundedIntOption
+  maxErrorsOption
 } from "./shared-options.js";
+import {
+  depthOption as threadDepthOption,
+  parentHeightOption as threadParentHeightOption,
+  parseThreadDepth
+} from "./thread-options.js";
+import { DurationInput, PositiveInt } from "./option-schemas.js";
 
 const intervalOption = Options.text("interval").pipe(
+  Options.withSchema(DurationInput),
   Options.withDescription(
     "Polling interval (e.g. \"30 seconds\", \"500 millis\") (default: 30 seconds)"
   ),
   Options.optional
 );
-const depthOption = Options.integer("depth").pipe(
-  Options.withDescription("Thread reply depth to include (0-1000, default 6)"),
+const maxCyclesOption = Options.integer("max-cycles").pipe(
+  Options.withSchema(PositiveInt),
+  Options.withDescription("Stop after N watch cycles"),
   Options.optional
 );
-const parentHeightOption = Options.integer("parent-height").pipe(
-  Options.withDescription("Thread parent height to include (0-1000, default 80)"),
+const untilOption = Options.text("until").pipe(
+  Options.withSchema(DurationInput),
+  Options.withDescription("Stop after a duration (e.g. \"10 minutes\")"),
   Options.optional
 );
+const depthOption = threadDepthOption(
+  "Thread reply depth to include (0-1000, default 6)"
+);
+const parentHeightOption = threadParentHeightOption(
+  "Thread parent height to include (0-1000, default 80)"
+);
 
 const timelineCommand = Command.make(
   "timeline",
@@ -56,6 +69,8 @@ const timelineCommand = Command.make(
     filter: filterOption,
     filterJson: filterJsonOption,
     interval: intervalOption,
+    maxCycles: maxCyclesOption,
+    until: untilOption,
     quiet: quietOption,
     refresh: refreshOption
   },
@@ -81,6 +96,8 @@ const feedCommand = Command.make(
     filter: filterOption,
     filterJson: filterJsonOption,
     interval: intervalOption,
+    maxCycles: maxCyclesOption,
+    until: untilOption,
     quiet: quietOption,
     refresh: refreshOption
   },
@@ -105,6 +122,8 @@ const listCommand = Command.make(
     filter: filterOption,
     filterJson: filterJsonOption,
     interval: intervalOption,
+    maxCycles: maxCyclesOption,
+    until: untilOption,
     quiet: quietOption,
     refresh: refreshOption
   },
@@ -128,6 +147,8 @@ const notificationsCommand = Command.make(
     filter: filterOption,
     filterJson: filterJsonOption,
     interval: intervalOption,
+    maxCycles: maxCyclesOption,
+    until: untilOption,
     quiet: quietOption,
     refresh: refreshOption
   },
@@ -152,19 +173,20 @@ const authorCommand = Command.make(
     postFilter: postFilterOption,
     postFilterJson: postFilterJsonOption,
     interval: intervalOption,
+    maxCycles: maxCyclesOption,
+    until: untilOption,
     quiet: quietOption,
     refresh: refreshOption
   },
-  ({ actor, filter, includePins, postFilter, postFilterJson, interval, store, quiet, refresh }) =>
+  ({ actor, filter, includePins, postFilter, postFilterJson, interval, maxCycles, until, store, quiet, refresh }) =>
     Effect.gen(function* () {
-      const resolvedActor = yield* decodeActor(actor);
       const apiFilter = Option.getOrUndefined(filter);
-      const source = DataSource.author(resolvedActor, {
+      const source = DataSource.author(actor, {
         ...(apiFilter !== undefined ? { filter: apiFilter } : {}),
         ...(includePins ? { includePins: true } : {})
       });
       const run = makeWatchCommandBody("author", () => source, {
-        actor: resolvedActor,
+        actor,
         ...(apiFilter !== undefined ? { filter: apiFilter } : {}),
         ...(includePins ? { includePins: true } : {})
       });
@@ -173,6 +195,8 @@ const authorCommand = Command.make(
         filter: postFilter,
         filterJson: postFilterJson,
         interval,
+        maxCycles,
+        until,
         quiet,
         refresh
       });
@@ -200,20 +224,15 @@ const threadCommand = Command.make(
     filter: filterOption,
     filterJson: filterJsonOption,
     interval: intervalOption,
+    maxCycles: maxCyclesOption,
+    until: untilOption,
     quiet: quietOption,
     refresh: refreshOption
   },
-  ({ uri, depth, parentHeight, filter, filterJson, interval, store, quiet, refresh }) =>
+  ({ uri, depth, parentHeight, filter, filterJson, interval, maxCycles, until, store, quiet, refresh }) =>
     Effect.gen(function* () {
-      const parsedDepth = yield* parseBoundedIntOption(depth, "depth", 0, 1000);
-      const parsedParentHeight = yield* parseBoundedIntOption(
-        parentHeight,
-        "parent-height",
-        0,
-        1000
-      );
-      const depthValue = Option.getOrUndefined(parsedDepth);
-      const parentHeightValue = Option.getOrUndefined(parsedParentHeight);
+      const { depth: depthValue, parentHeight: parentHeightValue } =
+        parseThreadDepth(depth, parentHeight);
       const source = DataSource.thread(uri, {
         ...(depthValue !== undefined ? { depth: depthValue } : {}),
         ...(parentHeightValue !== undefined ? { parentHeight: parentHeightValue } : {})
@@ -223,7 +242,7 @@ const threadCommand = Command.make(
         ...(depthValue !== undefined ? { depth: depthValue } : {}),
         ...(parentHeightValue !== undefined ? { parentHeight: parentHeightValue } : {})
       });
-      return yield* run({ store, filter, filterJson, interval, quiet, refresh });
+      return yield* run({ store, filter, filterJson, interval, maxCycles, until, quiet, refresh });
     })
 ).pipe(
   Command.withDescription(
@@ -251,6 +270,8 @@ const jetstreamCommand = Command.make(
     cursor: jetstreamOptions.cursor,
     compress: jetstreamOptions.compress,
     maxMessageSize: jetstreamOptions.maxMessageSize,
+    maxCycles: maxCyclesOption,
+    until: untilOption,
     strict: strictOption,
     maxErrors: maxErrorsOption
   },
@@ -265,6 +286,8 @@ const jetstreamCommand = Command.make(
     cursor,
     compress,
     maxMessageSize,
+    maxCycles,
+    until,
     strict,
     maxErrors
   }) =>
@@ -286,14 +309,14 @@ const jetstreamCommand = Command.make(
         storeRef,
         filterHash
       );
-      const parsedMaxErrors = yield* parseMaxErrors(maxErrors);
+      const parsedUntil = parseOptionalDuration(until);
       const engineLayer = JetstreamSyncEngine.layer.pipe(
         Layer.provideMerge(Jetstream.live(selection.config))
       );
       yield* logInfo("Starting watch", { source: "jetstream", store: storeRef.name });
       yield* Effect.gen(function* () {
         const engine = yield* JetstreamSyncEngine;
-        const maxErrorsValue = Option.getOrUndefined(parsedMaxErrors);
+        const maxErrorsValue = Option.getOrUndefined(maxErrors);
         const stream = engine.watch({
           source: selection.source,
           store: storeRef,
@@ -310,7 +333,13 @@ const jetstreamCommand = Command.make(
             makeSyncReporter(quiet, monitor, output)
           )
         );
-        return yield* writeJsonStream(outputStream);
+        const limited = Option.isSome(maxCycles)
+          ? outputStream.pipe(Stream.take(maxCycles.value))
+          : outputStream;
+        const timed = Option.isSome(parsedUntil)
+          ? limited.pipe(Stream.interruptWhen(Effect.sleep(parsedUntil.value)))
+          : limited;
+        return yield* writeJsonStream(timed);
       }).pipe(Effect.provide(engineLayer));
     })
 ).pipe(

package/src/domain/errors.ts

@@ -42,6 +42,11 @@ export class StoreNotFound extends Schema.TaggedError<StoreNotFound>()(
   { name: StoreName }
 ) {}
 
+export class StoreAlreadyExists extends Schema.TaggedError<StoreAlreadyExists>()(
+  "StoreAlreadyExists",
+  { name: StoreName }
+) {}
+
 export class StoreIoError extends Schema.TaggedError<StoreIoError>()(
   "StoreIoError",
   { path: StorePath, cause: Schema.Unknown }
@@ -68,4 +73,4 @@ export class FilterLibraryError extends Schema.TaggedError<FilterLibraryError>()
   }
 ) {}
 
-export type StoreError = StoreNotFound | StoreIoError | StoreIndexError;
+export type StoreError = StoreNotFound | StoreAlreadyExists | StoreIoError | StoreIndexError;

package/src/domain/format.ts

@@ -2,6 +2,7 @@ import { Post } from "./post.js";
 import { displayWidth, padEndDisplay } from "./text-width.js";
 
 const headers = ["Created At", "Author", "Text", "URI"];
+const headersWithStore = ["Store", ...headers];
 const textLimit = 80;
 
 export const normalizeWhitespace = (text: string) =>
@@ -41,6 +42,16 @@ const postToMarkdownRow = (post: Post) => [
   post.uri.replace(/\|/g, "\\|")
 ];
 
+const storePostToRow = (entry: { readonly store: string; readonly post: Post }) => [
+  entry.store,
+  ...postToRow(entry.post)
+];
+
+const storePostToMarkdownRow = (entry: { readonly store: string; readonly post: Post }) => [
+  entry.store,
+  ...postToMarkdownRow(entry.post)
+];
+
 const renderTable = (
   head: ReadonlyArray<string>,
   rows: ReadonlyArray<ReadonlyArray<string>>
@@ -89,3 +100,13 @@ export const renderPostsTable = (posts: ReadonlyArray<Post>) =>
 
 export const renderPostsMarkdown = (posts: ReadonlyArray<Post>) =>
   renderMarkdownTable(headers, posts.map(postToMarkdownRow));
+
+export const renderStorePostsTable = (
+  entries: ReadonlyArray<{ readonly store: string; readonly post: Post }>
+) =>
+  renderTable(headersWithStore, entries.map(storePostToRow));
+
+export const renderStorePostsMarkdown = (
+  entries: ReadonlyArray<{ readonly store: string; readonly post: Post }>
+) =>
+  renderMarkdownTable(headersWithStore, entries.map(storePostToMarkdownRow));

package/src/domain/order.ts

@@ -0,0 +1,24 @@
+import { Order } from "effect";
+import type { Post } from "./post.js";
+import type { StoreRef } from "./store.js";
+
+export const LocaleStringOrder = Order.make<string>((left, right) => {
+  const result = left.localeCompare(right);
+  if (result < 0) return -1;
+  if (result > 0) return 1;
+  return 0;
+});
+
+export const PostOrder = Order.mapInput(
+  Order.tuple(Order.Date, LocaleStringOrder),
+  (post: Post) => [post.createdAt, post.uri] as const
+);
+
+export const StorePostOrder = Order.mapInput(
+  Order.tuple(Order.Date, LocaleStringOrder, LocaleStringOrder),
+  (entry: { readonly post: Post; readonly store: StoreRef }) =>
+    [entry.post.createdAt, entry.post.uri, entry.store.name] as const
+);
+
+export const updatedAtOrder = <A extends { readonly updatedAt: Date }>() =>
+  Order.mapInput(Order.Date, (value: A) => value.updatedAt);

package/src/domain/primitives.ts

@@ -16,18 +16,35 @@ export const Hashtag = Schema.String.pipe(
 );
 export type Hashtag = typeof Hashtag.Type;
 
-export const AtUri = Schema.String.pipe(Schema.brand("AtUri"));
+const atUriPattern = /^at:\/\/\S+$/;
+
+export const AtUri = Schema.String.pipe(
+  Schema.pattern(atUriPattern),
+  Schema.brand("AtUri")
+);
 export type AtUri = typeof AtUri.Type;
 
-export const PostUri = Schema.String.pipe(Schema.brand("PostUri"));
+export const PostUri = Schema.String.pipe(
+  Schema.pattern(atUriPattern),
+  Schema.brand("PostUri")
+);
 export type PostUri = typeof PostUri.Type;
 
 export const PostCid = Schema.String.pipe(Schema.brand("PostCid"));
 export type PostCid = typeof PostCid.Type;
 
-export const Did = Schema.String.pipe(Schema.brand("Did"));
+export const Did = Schema.String.pipe(
+  Schema.pattern(/^did:\S+$/),
+  Schema.brand("Did")
+);
 export type Did = typeof Did.Type;
 
+export const ActorId = Schema.String.pipe(
+  Schema.pattern(/^(did:\S+|[a-z0-9][a-z0-9.-]{1,251})$/),
+  Schema.brand("ActorId")
+);
+export type ActorId = typeof ActorId.Type;
+
 export const Timestamp = Schema.Union(
   Schema.DateFromString,
   Schema.DateFromSelf