@classytic/arc 1.1.0 → 2.1.3

package/bin/arc.js

@@ -9,7 +9,9 @@
  *   arc generate controller <name>    Generate a controller only
  *   arc generate model <name>         Generate a model only
  *   arc introspect                    Show all registered resources
+ *   arc describe <entry-file>        Output JSON metadata for AI agents
  *   arc docs [output-path]            Export OpenAPI specification
+ *   arc doctor                        Check environment and dependencies
  *
  * Examples:
  *   arc init my-api
@@ -21,8 +23,6 @@
  */
 
 import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 function getPackageVersion() {
   try {
@@ -78,11 +78,20 @@ async function main() {
         await handleIntrospect(rest);
         break;
 
+      case 'describe':
+      case 'desc':
+        await handleDescribe(subcommand ? [subcommand, ...rest] : rest);
+        break;
+
       case 'docs':
       case 'd':
         await handleDocs(subcommand ? [subcommand, ...rest] : rest);
         break;
 
+      case 'doctor':
+        await handleDoctor(subcommand ? [subcommand, ...rest] : rest);
+        break;
+
       default:
         console.error(`Unknown command: ${command}`);
         console.error('Run "arc --help" for usage');
@@ -103,7 +112,7 @@ async function main() {
 
 async function handleInit(args) {
   const options = parseInitOptions(args);
-  const { init } = await import('../dist/cli/commands/init.js');
+  const { init } = await import('../dist/cli/commands/init.mjs');
   await init(options);
 }
 
@@ -146,72 +155,75 @@ async function handleGenerate(type, args) {
   }
 
   // Import and run
-  const { generate } = await import('../dist/cli/commands/generate.js');
+  const { generate } = await import('../dist/cli/commands/generate.mjs');
   await generate(normalizedType, args);
 }
 
-async function handleIntrospect(args) {
-  // Check for --entry flag
-  const entryIndex = args.findIndex(arg => arg === '--entry' || arg === '-e');
-  if (entryIndex !== -1 && args[entryIndex + 1]) {
-    const entryPath = args[entryIndex + 1];
-    // Resolve path relative to CWD and convert to file URL for ESM import
-    const absolutePath = resolve(process.cwd(), entryPath);
-    const fileUrl = pathToFileURL(absolutePath).href;
-
-    console.log(`Loading resources from: ${entryPath}\n`);
-    try {
-      await import(fileUrl);
-    } catch (err) {
-      console.error(`Failed to load entry file: ${err.message}`);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
-    }
-  }
+async function handleIntrospect(rawArgs) {
+  const args = normalizeArgs(rawArgs);
+  const { entryPath, filteredArgs } = extractEntryArg(args);
 
-  const { introspect } = await import('../dist/cli/commands/introspect.js');
-  await introspect(args.filter((arg, i) => arg !== '--entry' && arg !== '-e' && i !== entryIndex + 1));
+  const { introspect } = await import('../dist/cli/commands/introspect.mjs');
+  await introspect(entryPath ? [entryPath, ...filteredArgs] : filteredArgs);
 }
 
-async function handleDocs(args) {
-  // Check for --entry flag
-  const entryIndex = args.findIndex(arg => arg === '--entry' || arg === '-e');
-  if (entryIndex !== -1 && args[entryIndex + 1]) {
-    const entryPath = args[entryIndex + 1];
-    // Resolve path relative to CWD and convert to file URL for ESM import
-    const absolutePath = resolve(process.cwd(), entryPath);
-    const fileUrl = pathToFileURL(absolutePath).href;
-
-    console.log(`Loading resources from: ${entryPath}\n`);
-    try {
-      await import(fileUrl);
-    } catch (err) {
-      console.error(`Failed to load entry file: ${err.message}`);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
-    }
-  }
+async function handleDescribe(rawArgs) {
+  const args = normalizeArgs(rawArgs);
+  const { describe } = await import('../dist/cli/commands/describe.mjs');
+  await describe(args);
+}
+
+async function handleDocs(rawArgs) {
+  const args = normalizeArgs(rawArgs);
+  const { entryPath, filteredArgs } = extractEntryArg(args);
+  const { exportDocs } = await import('../dist/cli/commands/docs.mjs');
+  await exportDocs(entryPath ? [entryPath, ...filteredArgs] : filteredArgs);
+}
 
-  const filteredArgs = args.filter((arg, i) => arg !== '--entry' && arg !== '-e' && i !== entryIndex + 1);
-  const outputPath = filteredArgs[0] || './openapi.json';
-  const { exportDocs } = await import('../dist/cli/commands/docs.js');
-  await exportDocs([outputPath]);
+async function handleDoctor(rawArgs) {
+  const { doctor } = await import('../dist/cli/commands/doctor.mjs');
+  await doctor(rawArgs);
 }
 
 // ============================================================================
 // Option Parsing
 // ============================================================================
 
-function parseInitOptions(args) {
+// Mirrors src/cli/utils/normalizeArgs.ts — keep in sync
+// (bin/arc.js is unbundled, can't import tree-shaken dist internals)
+function normalizeArgs(raw) {
+  const out = [];
+  for (const arg of raw) {
+    if (arg.startsWith('--') && arg.includes('=')) {
+      const eqIdx = arg.indexOf('=');
+      out.push(arg.slice(0, eqIdx), arg.slice(eqIdx + 1));
+    } else {
+      out.push(arg);
+    }
+  }
+  return out;
+}
+
+function extractEntryArg(args) {
+  const entryIndex = args.findIndex(arg => arg === '--entry' || arg === '-e');
+  const hasEntry = entryIndex !== -1 && !!args[entryIndex + 1];
+  const entryPath = hasEntry ? args[entryIndex + 1] : undefined;
+  const filteredArgs = hasEntry
+    ? args.filter((arg, i) => i !== entryIndex && i !== entryIndex + 1)
+    : args;
+
+  return { entryPath, filteredArgs };
+}
+
+function parseInitOptions(rawArgs) {
+  const args = normalizeArgs(rawArgs);
+
   const opts = {
     name: undefined,
     adapter: undefined,
     tenant: undefined,
     typescript: undefined,
+    edge: undefined,
     skipInstall: false,
     force: false,
   };
@@ -261,6 +273,19 @@ function parseInitOptions(args) {
         opts.typescript = false;
         break;
 
+      case '--better-auth':
+        opts.auth = 'better-auth';
+        break;
+
+      case '--jwt':
+        opts.auth = 'jwt';
+        break;
+
+      case '--edge':
+      case '--serverless':
+        opts.edge = true;
+        break;
+
       case '--skip-install':
         opts.skipInstall = true;
         break;
@@ -291,7 +316,9 @@ COMMANDS
   init, new       Initialize a new Arc project
   generate, g     Generate resources, controllers, or models
   introspect, i   Show all registered resources
+  describe, desc  Output JSON metadata for AI agents
   docs, d         Export OpenAPI specification
+  doctor          Check environment and dependencies
 
 GLOBAL OPTIONS
   --entry, -e <path>       Entry file to load before running command
@@ -302,10 +329,13 @@ GLOBAL OPTIONS
 INIT OPTIONS
   --mongokit               Use MongoKit adapter (default, recommended)
   --custom                 Use custom adapter (empty template)
+  --better-auth            Use Better Auth (default, recommended)
+  --jwt                    Use Arc built-in JWT auth
   --multi-tenant, --multi  Multi-tenant mode (adds org scoping)
   --single-tenant, --single Single-tenant mode (default)
   --ts, --typescript       Generate TypeScript (default)
   --js, --javascript       Generate JavaScript
+  --edge, --serverless     Target Edge/Serverless environments
   --force, -f              Overwrite existing directory
   --skip-install           Skip npm install after scaffolding
 
@@ -326,7 +356,10 @@ EXAMPLES
   arc init my-api
 
   # Initialize with all options (non-interactive)
-  arc init my-api --mongokit --single --ts
+  arc init my-api --mongokit --better-auth --single --ts
+
+  # Initialize with JWT auth instead of Better Auth
+  arc init my-api --mongokit --jwt --single --ts
 
   # Initialize a JavaScript single-tenant app
   arc init my-api --mongokit --single --js
@@ -349,6 +382,12 @@ EXAMPLES
   # Show registered resources
   arc introspect --entry ./dist/index.js
 
+  # Output JSON metadata for AI agents
+  arc describe ./dist/resources.js --json
+
+  # Describe a single resource
+  arc describe ./dist/resources.js product
+
 MORE INFO
   Documentation: https://github.com/classytic/arc
   Issues: https://github.com/classytic/arc/issues

package/dist/EventTransport-BkUDYZEb.d.mts

@@ -0,0 +1,99 @@
+//#region src/events/EventTransport.d.ts
+/**
+ * Event Transport Interface
+ *
+ * Defines contract for event delivery backends.
+ * Implement for durable transports (Redis, RabbitMQ, Kafka, etc.)
+ *
+ * @example
+ * // Redis Pub/Sub implementation
+ * class RedisEventTransport implements EventTransport {
+ *   async publish(event) {
+ *     await redis.publish(event.type, JSON.stringify(event));
+ *   }
+ *   async subscribe(pattern, handler) {
+ *     redis.psubscribe(pattern);
+ *     redis.on('pmessage', (p, channel, msg) => handler(JSON.parse(msg)));
+ *   }
+ * }
+ */
+interface DomainEvent<T = unknown> {
+  /** Event type (e.g., 'product.created', 'order.shipped') */
+  type: string;
+  /** Event payload */
+  payload: T;
+  /** Event metadata */
+  meta: {
+    /** Unique event ID */id: string; /** Event timestamp */
+    timestamp: Date; /** Source resource */
+    resource?: string; /** Resource ID */
+    resourceId?: string; /** User who triggered the event */
+    userId?: string; /** Organization context */
+    organizationId?: string; /** Correlation ID for tracing */
+    correlationId?: string;
+  };
+}
+type EventHandler<T = unknown> = (event: DomainEvent<T>) => void | Promise<void>;
+/**
+ * Minimal logger interface for event transports.
+ * Compatible with `console`, `pino`, `fastify.log`, and any custom logger.
+ *
+ * @example
+ * ```typescript
+ * // Use Fastify's logger
+ * new MemoryEventTransport({ logger: fastify.log });
+ *
+ * // Use a custom logger
+ * new MemoryEventTransport({ logger: { warn: myWarn, error: myError } });
+ *
+ * // Default: console (no logger option needed)
+ * new MemoryEventTransport();
+ * ```
+ */
+interface EventLogger {
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+interface EventTransport {
+  /** Transport name for logging */
+  readonly name: string;
+  /**
+   * Publish an event to the transport
+   */
+  publish(event: DomainEvent): Promise<void>;
+  /**
+   * Subscribe to events matching a pattern
+   * @param pattern - Event type pattern (e.g., 'product.*', '*')
+   * @param handler - Handler function
+   * @returns Unsubscribe function
+   */
+  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
+  /**
+   * Close transport connections
+   */
+  close?(): Promise<void>;
+}
+interface MemoryEventTransportOptions {
+  /** Logger for error/warning messages (default: console) */
+  logger?: EventLogger;
+}
+/**
+ * In-memory event transport (default)
+ * Events are delivered synchronously within the process.
+ * Not suitable for multi-instance deployments.
+ */
+declare class MemoryEventTransport implements EventTransport {
+  readonly name = "memory";
+  private handlers;
+  private logger;
+  constructor(options?: MemoryEventTransportOptions);
+  publish(event: DomainEvent): Promise<void>;
+  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
+  close(): Promise<void>;
+}
+/**
+ * Create a domain event with auto-generated metadata
+ */
+declare function createEvent<T>(type: string, payload: T, meta?: Partial<DomainEvent['meta']>): DomainEvent<T>;
+//#endregion
+export { MemoryEventTransport as a, EventTransport as i, EventHandler as n, MemoryEventTransportOptions as o, EventLogger as r, createEvent as s, DomainEvent as t };