@mepuka/skygent 0.2.0

package/README.md

@@ -0,0 +1,59 @@
+# skygent-bsky
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+Create a local `.env` from `.env.example` and set credentials:
+
+```bash
+cp .env.example .env
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+## Quickstart
+
+```bash
+# List stores (compact JSON for agents)
+bun run index.ts store list --compact
+
+# Sync timeline into a store
+bun run index.ts sync timeline --store my-store --quiet
+
+# Query recent posts as a table
+bun run index.ts query my-store --limit 10 --format table
+
+# Stream Jetstream posts
+bun run index.ts watch jetstream --store my-store --quiet
+```
+
+Tips:
+- Add `--compact` to reduce JSON output size.
+- Add `--quiet` to suppress progress logs during sync/watch commands.
+
+## Documentation
+
+- docs/README.md
+- docs/getting-started.md
+- docs/cli.md
+- docs/filters.md
+- docs/configuration.md
+- docs/credentials.md
+- docs/stores.md
+- docs/outputs.md
+
+## Security notes
+
+- Credentials are loaded via Effect `Redacted` config and are not logged.
+- Encrypted credential storage uses `SKYGENT_CREDENTIALS_KEY` (AES-GCM).
+- Avoid putting passwords in `config.json`; use env or the credential store instead.
+- Resource warnings can be configured via `SKYGENT_RESOURCE_*` env vars.
+
+This project was created using `bun init` in bun v1.3.4. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/index.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env bun
+import { Command, HelpDoc, ValidationError } from "@effect/cli";
+import { BunContext, BunRuntime } from "@effect/platform-bun";
+import { Effect, Layer } from "effect";
+import { app } from "./src/cli/app.js";
+import pkg from "./package.json" with { type: "json" };
+import {
+  type AgentErrorPayload,
+  CliInputError,
+  CliJsonError,
+  parseAgentErrorPayload
+} from "./src/cli/errors.js";
+import { logErrorEvent } from "./src/cli/logging.js";
+import { CliOutput } from "./src/cli/output.js";
+import { exitCodeFor, exitCodeFromExit } from "./src/cli/exit-codes.js";
+import { BskyError, StoreNotFound } from "./src/domain/errors.js";
+
+const cli = Command.run(app, {
+  name: "skygent",
+  version: pkg.version
+});
+
+const stripAnsi = (value: string) =>
+  value.replace(/\u001b\[[0-9;]*m/g, "");
+
+const formatValidationError = (error: ValidationError.ValidationError) => {
+  const text = HelpDoc.toAnsiText(error.error).trimEnd();
+  return stripAnsi(text.length > 0 ? text : "Invalid command input. Use --help for usage.");
+};
+
+const getAgentPayload = (error: unknown): AgentErrorPayload | undefined => {
+  if (error instanceof CliJsonError || error instanceof CliInputError) {
+    return parseAgentErrorPayload(error.message);
+  }
+  return undefined;
+};
+
+const formatError = (error: unknown, agentPayload?: AgentErrorPayload) => {
+  if (agentPayload) {
+    return agentPayload.message;
+  }
+  if (ValidationError.isValidationError(error)) {
+    return formatValidationError(error);
+  }
+  if (error instanceof CliJsonError) {
+    return error.message;
+  }
+  if (error instanceof CliInputError) {
+    return error.message;
+  }
+  if (error instanceof StoreNotFound) {
+    return `Store \"${error.name}\" does not exist.`;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    typeof (error as { readonly message?: unknown }).message === "string"
+  ) {
+    return (error as { readonly message: string }).message;
+  }
+  if (typeof error === "object" && error !== null && "_tag" in error) {
+    return JSON.stringify(error);
+  }
+  return String(error);
+};
+
+const errorType = (error: unknown, agentPayload?: AgentErrorPayload): string => {
+  if (agentPayload) return agentPayload.error;
+  if (ValidationError.isValidationError(error)) return "ValidationError";
+  if (error instanceof Error) return error.name;
+  if (typeof error === "object" && error !== null && "_tag" in error) {
+    return String((error as { readonly _tag?: unknown })._tag ?? "UnknownError");
+  }
+  return "UnknownError";
+};
+
+const errorDetails = (
+  error: unknown,
+  agentPayload?: AgentErrorPayload
+): Record<string, unknown> | undefined => {
+  if (agentPayload) {
+    return { error: agentPayload };
+  }
+  if (error instanceof StoreNotFound) {
+    return { error: { _tag: "StoreNotFound", name: error.name } };
+  }
+  if (error instanceof BskyError) {
+    return {
+      error: {
+        _tag: "BskyError",
+        ...(error.operation ? { operation: error.operation } : {}),
+        ...(typeof error.status === "number" ? { status: error.status } : {})
+      }
+    };
+  }
+  if (error instanceof CliJsonError || error instanceof CliInputError) {
+    return undefined;
+  }
+  if (typeof error === "object" && error !== null && "_tag" in error) {
+    return { error };
+  }
+  return undefined;
+};
+
+const errorSuggestion = (
+  error: unknown,
+  agentPayload?: AgentErrorPayload
+): string | undefined => {
+  if (agentPayload?.fix) return agentPayload.fix;
+  if (error instanceof StoreNotFound) {
+    return `Run: skygent store create ${error.name}`;
+  }
+  return undefined;
+};
+
+const program = cli(process.argv).pipe(
+  Effect.tapError((error) => {
+    if (ValidationError.isValidationError(error)) {
+      return Effect.void;
+    }
+    const agentPayload = getAgentPayload(error);
+    return logErrorEvent(formatError(error, agentPayload), {
+      code: exitCodeFor(error),
+      type: errorType(error, agentPayload),
+      suggestion: errorSuggestion(error, agentPayload),
+      ...errorDetails(error, agentPayload)
+    });
+  }),
+  Effect.provide(Layer.mergeAll(BunContext.layer, CliOutput.layer))
+);
+
+BunRuntime.runMain({
+  disableErrorReporting: true,
+  disablePrettyLogger: true,
+  teardown: (exit, onExit) => {
+    const code = exitCodeFromExit(exit);
+    onExit(code);
+    if (typeof process !== "undefined") {
+      process.exit(code);
+    }
+  }
+})(program);

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mepuka/skygent",
+  "version": "0.2.0",
+  "description": "Composable Bluesky data filtering and monitoring CLI built with Effect",
+  "module": "index.ts",
+  "type": "module",
+  "bin": {
+    "skygent": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mepuka/skygent-bsky.git"
+  },
+  "scripts": {
+    "prepare": "effect-language-service patch",
+    "build": "tsc --build",
+    "build:clean": "rm -rf dist .tsbuildinfo && bun run build",
+    "build:binary": "bun build --compile index.ts --outfile skygent",
+    "build:binary:linux-x64": "bun build --compile --target=bun-linux-x64 index.ts --outfile skygent-linux-x64",
+    "build:binary:linux-arm64": "bun build --compile --target=bun-linux-arm64 index.ts --outfile skygent-linux-arm64",
+    "build:binary:darwin-x64": "bun build --compile --target=bun-darwin-x64 index.ts --outfile skygent-darwin-x64",
+    "build:binary:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 index.ts --outfile skygent-darwin-arm64",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "bun run build && changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@effect/language-service": "^0.72.0",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@atproto/api": "^0.18.17",
+    "@effect/cli": "^0.73.1",
+    "@effect/platform": "^0.94.2",
+    "@effect/platform-bun": "^0.87.1",
+    "@effect/printer": "^0.47.0",
+    "@effect/printer-ansi": "^0.47.0",
+    "@effect/sql": "^0.49.0",
+    "@effect/sql-sqlite-bun": "^0.50.0",
+    "@effect/typeclass": "^0.38.0",
+    "effect": "^3.19.15",
+    "effect-jetstream": "^1.0.4"
+  }
+}

package/src/cli/app.ts

@@ -0,0 +1,75 @@
+import { Command } from "@effect/cli";
+import { Layer, Option } from "effect";
+import { CliLive } from "./layers.js";
+import { ConfigOverrides } from "../services/app-config.js";
+import { CredentialsOverrides } from "../services/credential-store.js";
+import { DerivationSettingsOverrides } from "../services/derivation-settings.js";
+import { SyncSettingsOverrides } from "../services/sync-settings.js";
+import { CliPreferences } from "./preferences.js";
+import { storeCommand } from "./store.js";
+import { syncCommand } from "./sync.js";
+import { queryCommand } from "./query.js";
+import { watchCommand } from "./watch.js";
+import { deriveCommand } from "./derive.js";
+import { viewCommand } from "./view.js";
+import { filterCommand } from "./filter.js";
+import { searchCommand } from "./search.js";
+import { graphCommand } from "./graph.js";
+import { feedCommand } from "./feed.js";
+import { postCommand } from "./post.js";
+import { configCommand } from "./config-command.js";
+import {
+  configOptions,
+  toConfigOverrides,
+  toCredentialsOverrides,
+  toSyncSettingsOverrides
+} from "./config.js";
+import { withExamples } from "./help.js";
+
+export const app = Command.make("skygent", configOptions).pipe(
+  Command.withSubcommands([
+    configCommand,
+    storeCommand,
+    syncCommand,
+    queryCommand,
+    watchCommand,
+    deriveCommand,
+    viewCommand,
+    filterCommand,
+    searchCommand,
+    graphCommand,
+    feedCommand,
+    postCommand
+  ]),
+  Command.provide((config) =>
+    Layer.mergeAll(
+      CliLive.pipe(
+        Layer.provide(
+          Layer.mergeAll(
+            Layer.succeed(ConfigOverrides, toConfigOverrides(config)),
+            Layer.succeed(CredentialsOverrides, toCredentialsOverrides(config)),
+            Layer.succeed(SyncSettingsOverrides, toSyncSettingsOverrides(config)),
+            DerivationSettingsOverrides.layer
+          )
+        )
+      ),
+      Layer.succeed(
+        CliPreferences,
+        Option.match(config.logFormat, {
+          onNone: () => ({ compact: config.compact }),
+          onSome: (logFormat) => ({ compact: config.compact, logFormat })
+        })
+      )
+    )
+  ),
+  Command.withDescription(
+    withExamples(
+      "Skygent CLI for Bluesky monitoring",
+      [
+        "skygent store list --compact",
+        "skygent sync timeline --store my-store --quiet"
+      ],
+      ["Tip: add --compact for shorter JSON output."]
+    )
+  )
+);

package/src/cli/config-command.ts

@@ -0,0 +1,140 @@
+import { Command } from "@effect/cli";
+import { FileSystem, Path } from "@effect/platform";
+import { Options } from "@effect/cli";
+import { Clock, Effect, Option, Stream } from "effect";
+import { withExamples } from "./help.js";
+import { writeJson, writeText } from "./output.js";
+import { renderTableLegacy } from "./doc/table.js";
+import { AppConfigService } from "../services/app-config.js";
+import { CredentialStore } from "../services/credential-store.js";
+import { BskyClient } from "../services/bsky-client.js";
+import { jsonTableFormats, resolveOutputFormat } from "./output-format.js";
+
+type CheckStatus = "ok" | "warn" | "error";
+
+type CheckResult = {
+  readonly name: string;
+  readonly status: CheckStatus;
+  readonly message?: string;
+};
+
+const checkOk = (name: string, message?: string): CheckResult =>
+  message ? { name, status: "ok", message } : { name, status: "ok" };
+
+const checkWarn = (name: string, message: string): CheckResult => ({
+  name,
+  status: "warn",
+  message
+});
+
+const checkError = (name: string, message: string): CheckResult => ({
+  name,
+  status: "error",
+  message
+});
+
+const checkFormatOption = Options.choice("format", jsonTableFormats).pipe(
+  Options.withDescription("Output format (default: json)"),
+  Options.optional
+);
+
+const configCheckCommand = Command.make("check", { format: checkFormatOption }, ({ format }) =>
+  Effect.gen(function* () {
+    const results: Array<CheckResult> = [];
+
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const config = yield* AppConfigService;
+    const credentials = yield* CredentialStore;
+    const bsky = yield* BskyClient;
+    // Store root writable
+    const rootCheck = yield* Effect.gen(function* () {
+      yield* fs.makeDirectory(config.storeRoot, { recursive: true });
+      const now = yield* Clock.currentTimeMillis;
+      const probePath = path.join(
+        config.storeRoot,
+        `.skygent-check-${now}`
+      );
+      yield* fs.writeFileString(probePath, "ok");
+      yield* fs.remove(probePath);
+      return checkOk("store-root", "Store root is writable.");
+    }).pipe(
+      Effect.catchAll((error) =>
+        Effect.succeed(
+          checkError(
+            "store-root",
+            error instanceof Error ? error.message : String(error)
+          )
+        )
+      )
+    );
+    results.push(rootCheck);
+
+    // Credential file + key
+    const credentialCheck = yield* credentials.get().pipe(
+      Effect.match({
+        onFailure: (error) =>
+          checkError("credentials", error.message ?? "Failed to load credentials"),
+        onSuccess: (value) =>
+          Option.isSome(value)
+            ? checkOk("credentials", "Credentials loaded.")
+            : checkWarn("credentials", "No credentials configured.")
+      })
+    );
+    results.push(credentialCheck);
+
+    // Bluesky auth
+    if (credentialCheck.status === "ok") {
+      const bskyCheck = yield* bsky
+        .getTimeline({ limit: 1 })
+        .pipe(
+          Stream.take(1),
+          Stream.runCollect,
+          Effect.as(checkOk("bluesky", "Bluesky login succeeded.")),
+          Effect.catchAll((error) =>
+            Effect.succeed(
+              checkError(
+                "bluesky",
+                error instanceof Error ? error.message : String(error)
+              )
+            )
+          )
+        );
+      results.push(bskyCheck);
+    } else {
+      results.push(
+        checkWarn("bluesky", "Skipped Bluesky login (credentials missing).")
+      );
+    }
+
+    const ok = results.every((result) => result.status !== "error");
+    const outputFormat = resolveOutputFormat(
+      format,
+      config.outputFormat,
+      jsonTableFormats,
+      "json"
+    );
+    
+    if (outputFormat === "table") {
+      const rows = results.map((r) => [
+        r.status === "ok" ? "✓" : r.status === "warn" ? "⚠" : "✗",
+        r.name,
+        r.message || r.status
+      ]);
+      const table = renderTableLegacy(["STATUS", "CHECK", "DETAILS"], rows);
+      yield* writeText(`${ok ? "✓ Config valid" : "✗ Config has errors"}\n\n${table}`);
+      return;
+    }
+    
+    yield* writeJson({ ok, checks: results });
+  })
+).pipe(
+  Command.withDescription("Run health checks (store root, credentials, Bluesky auth)")
+);
+
+export const configCommand = Command.make("config", {}).pipe(
+  Command.withSubcommands([configCheckCommand]),
+  Command.withDescription(
+    withExamples("Configuration helpers", ["skygent config check"])
+  )
+);

package/src/cli/config.ts

@@ -0,0 +1,91 @@
+import { Options } from "@effect/cli";
+import { Option, Redacted } from "effect";
+import { pickDefined } from "../services/shared.js";
+import { OutputFormat } from "../domain/config.js";
+import { AppConfig } from "../domain/config.js";
+import type { LogFormat } from "./logging.js";
+import type { SyncSettingsValue } from "../services/sync-settings.js";
+import type { CredentialsOverridesValue } from "../services/credential-store.js";
+
+
+export const configOptions = {
+  service: Options.text("service").pipe(
+    Options.optional,
+    Options.withDescription("Override the Bluesky service URL")
+  ),
+  storeRoot: Options.text("store-root").pipe(
+    Options.optional,
+    Options.withDescription("Override the root storage directory")
+  ),
+  outputFormat: Options.choice("output-format", [
+    "json",
+    "ndjson",
+    "markdown",
+    "table"
+  ]).pipe(Options.optional, Options.withDescription("Default output format")),
+  identifier: Options.text("identifier").pipe(
+    Options.optional,
+    Options.withDescription("Override Bluesky identifier")
+  ),
+  password: Options.redacted("password").pipe(
+    Options.optional,
+    Options.withDescription("Override Bluesky password (redacted)")
+  ),
+  compact: Options.boolean("compact").pipe(
+    Options.withDescription("Reduce JSON output verbosity for agent consumption")
+  ),
+  logFormat: Options.choice("log-format", ["json", "human"]).pipe(
+    Options.optional,
+    Options.withDescription("Override log format (json or human)")
+  ),
+  syncConcurrency: Options.integer("sync-concurrency").pipe(
+    Options.optional,
+    Options.withDescription("Concurrent sync preparation workers (default: 5)")
+  ),
+  checkpointEvery: Options.integer("checkpoint-every").pipe(
+    Options.optional,
+    Options.withDescription("Checkpoint every N processed posts (default: 100)")
+  ),
+  checkpointIntervalMs: Options.integer("checkpoint-interval-ms").pipe(
+    Options.optional,
+    Options.withDescription("Checkpoint interval in milliseconds (default: 5000)")
+  )
+};
+
+export type ConfigOptions = {
+  readonly service: Option.Option<string>;
+  readonly storeRoot: Option.Option<string>;
+  readonly outputFormat: Option.Option<OutputFormat>;
+  readonly identifier: Option.Option<string>;
+  readonly password: Option.Option<Redacted.Redacted<string>>;
+  readonly compact: boolean;
+  readonly logFormat: Option.Option<LogFormat>;
+  readonly syncConcurrency: Option.Option<number>;
+  readonly checkpointEvery: Option.Option<number>;
+  readonly checkpointIntervalMs: Option.Option<number>;
+};
+
+export const toConfigOverrides = (options: ConfigOptions): Partial<AppConfig> =>
+  pickDefined({
+    service: Option.getOrUndefined(options.service),
+    storeRoot: Option.getOrUndefined(options.storeRoot),
+    outputFormat: Option.getOrUndefined(options.outputFormat),
+    identifier: Option.getOrUndefined(options.identifier)
+  }) as Partial<AppConfig>;
+
+export const toCredentialsOverrides = (
+  options: ConfigOptions
+): CredentialsOverridesValue =>
+  pickDefined({
+    identifier: Option.getOrUndefined(options.identifier),
+    password: Option.getOrUndefined(options.password)
+  }) as CredentialsOverridesValue;
+
+export const toSyncSettingsOverrides = (
+  options: ConfigOptions
+): Partial<SyncSettingsValue> =>
+  pickDefined({
+    concurrency: Option.getOrUndefined(options.syncConcurrency),
+    checkpointEvery: Option.getOrUndefined(options.checkpointEvery),
+    checkpointIntervalMs: Option.getOrUndefined(options.checkpointIntervalMs)
+  }) as Partial<SyncSettingsValue>;