@primstack/cli 0.0.1

package/dist/integrations/flags/providers/local/templates/api/src/lib/flags.ts.template

@@ -0,0 +1,97 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface FlagDefinition {
+  enabled: boolean;
+  description?: string;
+  variants?: Record<string, number>;
+}
+
+interface FlagsConfig {
+  flags: Record<string, FlagDefinition>;
+}
+
+// Load flags from JSON file
+function loadFlags(): FlagsConfig {
+  // Try project root first (for monorepo), then cwd
+  const possiblePaths = [
+    path.join(process.cwd(), '..', '..', 'flags.json'),  // apps/api -> root
+    path.join(process.cwd(), 'flags.json'),
+  ];
+
+  const flagsPath = possiblePaths.find(p => fs.existsSync(p));
+
+  if (!flagsPath) {
+    return { flags: {} };
+  }
+
+  const content = fs.readFileSync(flagsPath, 'utf-8');
+  return JSON.parse(content) as FlagsConfig;
+}
+
+// Cache flags in memory (reload on each request in dev, cache in prod)
+let cachedFlags: FlagsConfig | null = null;
+
+function getFlags(): FlagsConfig {
+  if (process.env.NODE_ENV === 'production' && cachedFlags) {
+    return cachedFlags;
+  }
+  cachedFlags = loadFlags();
+  return cachedFlags;
+}
+
+/**
+ * Check if a feature flag is enabled
+ */
+export function getFlag(key: string, defaultValue = false): boolean {
+  const flags = getFlags();
+  return flags.flags[key]?.enabled ?? defaultValue;
+}
+
+/**
+ * Get a deterministic variant for a user based on their ID
+ * Uses a simple hash to ensure the same user always gets the same variant
+ */
+export function getFlagVariant(key: string, userId: string): string | null {
+  const flags = getFlags();
+  const flag = flags.flags[key];
+
+  if (!flag?.enabled || !flag.variants) {
+    return null;
+  }
+
+  // Simple deterministic hash based on userId and flag key
+  const hash = simpleHash(userId + key);
+  const variants = Object.entries(flag.variants);
+  let cumulative = 0;
+
+  for (const [variant, weight] of variants) {
+    cumulative += weight;
+    if (hash % 100 < cumulative) {
+      return variant;
+    }
+  }
+
+  // Fallback to first variant
+  return variants[0]?.[0] ?? null;
+}
+
+/**
+ * Get all flags (for debugging/admin)
+ */
+export function getAllFlags(): FlagsConfig {
+  return getFlags();
+}
+
+/**
+ * Simple hash function for deterministic variant assignment
+ */
+function simpleHash(str: string): number {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32-bit integer
+  }
+  return Math.abs(hash);
+}

package/dist/integrations/flags/providers/local/templates/api/src/routes/flags.ts.template

@@ -0,0 +1,36 @@
+import { FastifyPluginAsync } from 'fastify';
+import { getFlag, getFlagVariant, getAllFlags } from '../lib/flags.js';
+
+export const flagsRoutes: FastifyPluginAsync = async (fastify) => {
+  // Get all flags (admin/debug)
+  fastify.get('/', async (request, reply) => {
+    // In production, you might want to protect this endpoint
+    const flags = getAllFlags();
+    return reply.send(flags);
+  });
+
+  // Get a specific flag
+  fastify.get<{ Params: { key: string } }>('/:key', async (request, reply) => {
+    const { key } = request.params;
+    const enabled = getFlag(key);
+    return reply.send({ key, enabled });
+  });
+
+  // Get variant for a flag (requires userId in query or from auth)
+  fastify.get<{ Params: { key: string }; Querystring: { userId?: string } }>(
+    '/:key/variant',
+    async (request, reply) => {
+      const { key } = request.params;
+      const userId = request.query.userId || (request as any).user?.id;
+
+      if (!userId) {
+        return reply.status(400).send({ error: 'userId is required for variant assignment' });
+      }
+
+      const variant = getFlagVariant(key, userId);
+      return reply.send({ key, variant });
+    }
+  );
+};
+
+export default flagsRoutes;

package/dist/integrations/flags/providers/local/templates/flags.json.template

@@ -0,0 +1,8 @@
+{
+  "flags": {
+    "example-feature": {
+      "enabled": false,
+      "description": "Example feature flag - delete or modify as needed"
+    }
+  }
+}

package/dist/integrations/flags/providers/local/templates/web/src/hooks/use-flag.ts.template

@@ -0,0 +1,60 @@
+import { useState, useEffect } from 'react';
+
+/**
+ * Check if a feature flag is enabled
+ * Fetches the flag value from the API
+ */
+export function useFlag(key: string, defaultValue = false): boolean {
+  const [enabled, setEnabled] = useState(defaultValue);
+
+  useEffect(() => {
+    fetch(`/api/flags/${key}`)
+      .then((res) => {
+        if (!res.ok) throw new Error('Failed to fetch flag');
+        return res.json();
+      })
+      .then((data) => setEnabled(data.enabled))
+      .catch(() => setEnabled(defaultValue));
+  }, [key, defaultValue]);
+
+  return enabled;
+}
+
+/**
+ * Get the variant assigned to the current user for a feature flag
+ * Requires userId to be passed or available from auth context
+ */
+export function useFlagVariant(key: string, userId?: string): string | null {
+  const [variant, setVariant] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!userId) return;
+
+    fetch(`/api/flags/${key}/variant?userId=${encodeURIComponent(userId)}`)
+      .then((res) => {
+        if (!res.ok) throw new Error('Failed to fetch variant');
+        return res.json();
+      })
+      .then((data) => setVariant(data.variant))
+      .catch(() => setVariant(null));
+  }, [key, userId]);
+
+  return variant;
+}
+
+/**
+ * Sync hook that checks flag on component mount
+ * Useful for server-rendered pages where you want to check flags early
+ */
+export function useFlagSync(key: string): { enabled: boolean; loading: boolean } {
+  const [state, setState] = useState({ enabled: false, loading: true });
+
+  useEffect(() => {
+    fetch(`/api/flags/${key}`)
+      .then((res) => res.json())
+      .then((data) => setState({ enabled: data.enabled, loading: false }))
+      .catch(() => setState({ enabled: false, loading: false }));
+  }, [key]);
+
+  return state;
+}

package/dist/integrations/logging/providers/axiom/templates/src/logging/index.ts.template

@@ -0,0 +1,56 @@
+import winston from 'winston';
+import { WinstonTransport as AxiomTransport } from '@axiomhq/winston';
+
+const isProduction = process.env.NODE_ENV === 'production';
+
+const transports: winston.transport[] = [new winston.transports.Console()];
+
+if (isProduction && process.env.AXIOM_TOKEN) {
+  transports.push(
+    new AxiomTransport({
+      dataset: process.env.AXIOM_DATASET || 'logs',
+      token: process.env.AXIOM_TOKEN!,
+    }),
+  );
+}
+
+export const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: isProduction
+    ? winston.format.json()
+    : winston.format.combine(
+        winston.format.colorize(),
+        winston.format.simple(),
+      ),
+  transports,
+});
+
+export function createLogger(name: string) {
+  return winston.createLogger({
+    level: process.env.LOG_LEVEL || 'info',
+    defaultMeta: { name },
+    format: isProduction
+      ? winston.format.json()
+      : winston.format.combine(
+          winston.format.colorize(),
+          winston.format.simple(),
+        ),
+    transports,
+  });
+}
+
+export async function flushLogs(): Promise<void> {
+  const promises = transports.map(
+    (t) =>
+      new Promise<void>((resolve) => {
+        if (typeof (t as AxiomTransport).flush === 'function') {
+          (t as AxiomTransport).flush!().then(() => resolve()).catch(() => resolve());
+        } else {
+          resolve();
+        }
+      }),
+  );
+  await Promise.all(promises);
+}
+
+export type { LogLevel, LogContext } from './types.js';

package/dist/integrations/logging/providers/axiom/templates/src/logging/types.ts.template

@@ -0,0 +1,5 @@
+export type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly';
+
+export interface LogContext {
+  [key: string]: unknown;
+}

package/dist/integrations/logging/providers/pino/templates/src/logging/index.ts.template

@@ -0,0 +1,21 @@
+import pino from 'pino';
+
+const isProduction = process.env.NODE_ENV === 'production';
+
+export const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  ...(isProduction
+    ? {}
+    : {
+        transport: {
+          target: 'pino-pretty',
+          options: { colorize: true },
+        },
+      }),
+});
+
+export function createLogger(name: string) {
+  return logger.child({ name });
+}
+
+export type { LogLevel, LogContext } from './types.js';

package/dist/integrations/logging/providers/pino/templates/src/logging/types.ts.template

@@ -0,0 +1,5 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+export interface LogContext {
+  [key: string]: unknown;
+}

package/dist/integrations/logging/providers/winston/templates/src/logging/index.ts.template

@@ -0,0 +1,30 @@
+import winston from 'winston';
+
+const isProduction = process.env.NODE_ENV === 'production';
+
+export const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: isProduction
+    ? winston.format.json()
+    : winston.format.combine(
+        winston.format.colorize(),
+        winston.format.simple(),
+      ),
+  transports: [new winston.transports.Console()],
+});
+
+export function createLogger(name: string) {
+  return winston.createLogger({
+    level: process.env.LOG_LEVEL || 'info',
+    defaultMeta: { name },
+    format: isProduction
+      ? winston.format.json()
+      : winston.format.combine(
+          winston.format.colorize(),
+          winston.format.simple(),
+        ),
+    transports: [new winston.transports.Console()],
+  });
+}
+
+export type { LogLevel, LogContext } from './types.js';

package/dist/integrations/logging/providers/winston/templates/src/logging/types.ts.template

@@ -0,0 +1,5 @@
+export type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly';
+
+export interface LogContext {
+  [key: string]: unknown;
+}

package/dist/integrations/monitor/providers/datadog/templates/src/monitor/index.ts.template

@@ -0,0 +1,78 @@
+import tracer from 'dd-trace';
+import type { MonitorConfig, ErrorContext } from './types.js';
+
+let initialized = false;
+
+export function initMonitoring(config?: Partial<MonitorConfig>): boolean {
+  if (initialized) return true;
+
+  const apiKey = process.env.DD_API_KEY;
+  if (!apiKey) {
+    console.warn('[monitor] DD_API_KEY not set — monitoring disabled');
+    return false;
+  }
+
+  tracer.init({
+    env: config?.environment ?? process.env.DD_ENV ?? 'development',
+    version: config?.release,
+    sampleRate: config?.sampleRate ?? 1.0,
+    logInjection: true,
+    runtimeMetrics: true,
+  });
+
+  initialized = true;
+  return true;
+}
+
+export function captureError(error: Error, context?: ErrorContext): void {
+  if (!initialized) return;
+
+  const span = tracer.scope().active();
+  if (span) {
+    span.setTag('error', true);
+    span.setTag('error.message', error.message);
+    span.setTag('error.stack', error.stack ?? '');
+    if (context?.user) {
+      span.setTag('usr.id', context.user.id);
+      if (context.user.email) span.setTag('usr.email', context.user.email);
+    }
+    if (context?.tags) {
+      for (const [key, value] of Object.entries(context.tags)) {
+        span.setTag(key, value);
+      }
+    }
+  }
+}
+
+export function captureMessage(
+  message: string,
+  level: 'info' | 'warning' | 'error' = 'info',
+): void {
+  if (!initialized) return;
+
+  const span = tracer.scope().active();
+  if (span) {
+    span.setTag(`message.${level}`, message);
+  }
+}
+
+export function setUser(user: { id: string; email?: string }): void {
+  if (!initialized) return;
+
+  const span = tracer.scope().active();
+  if (span) {
+    span.setTag('usr.id', user.id);
+    if (user.email) span.setTag('usr.email', user.email);
+  }
+}
+
+export async function startSpan<T>(
+  name: string,
+  op: string,
+  callback: () => T | Promise<T>,
+): Promise<T> {
+  if (!initialized) return callback();
+  return tracer.trace(`${op}.${name}`, callback);
+}
+
+export type { MonitorConfig, ErrorContext } from './types.js';

package/dist/integrations/monitor/providers/datadog/templates/src/monitor/types.ts.template

@@ -0,0 +1,12 @@
+export interface MonitorConfig {
+  enabled: boolean;
+  environment?: string;
+  release?: string;
+  sampleRate?: number;
+}
+
+export interface ErrorContext {
+  user?: { id: string; email?: string };
+  tags?: Record<string, string>;
+  extra?: Record<string, unknown>;
+}

package/dist/integrations/monitor/providers/newrelic/templates/src/monitor/index.ts.template

@@ -0,0 +1,60 @@
+import newrelic from 'newrelic';
+import type { MonitorConfig, ErrorContext } from './types.js';
+
+let initialized = false;
+
+export function initMonitoring(_config?: Partial<MonitorConfig>): boolean {
+  if (initialized) return true;
+
+  const licenseKey = process.env.NEW_RELIC_LICENSE_KEY;
+  if (!licenseKey) {
+    console.warn('[monitor] NEW_RELIC_LICENSE_KEY not set — monitoring disabled');
+    return false;
+  }
+
+  // New Relic auto-initializes via require/import — agent is already running
+  initialized = true;
+  return true;
+}
+
+export function captureError(error: Error, context?: ErrorContext): void {
+  if (!initialized) return;
+
+  const customAttributes: Record<string, string> = {};
+  if (context?.user) {
+    customAttributes['user.id'] = context.user.id;
+    if (context.user.email) customAttributes['user.email'] = context.user.email;
+  }
+  if (context?.tags) {
+    Object.assign(customAttributes, context.tags);
+  }
+
+  newrelic.noticeError(error, customAttributes);
+}
+
+export function captureMessage(
+  message: string,
+  level: 'info' | 'warning' | 'error' = 'info',
+): void {
+  if (!initialized) return;
+  newrelic.recordCustomEvent('CustomMessage', { message, level });
+}
+
+export function setUser(user: { id: string; email?: string }): void {
+  if (!initialized) return;
+  newrelic.addCustomAttributes({
+    'user.id': user.id,
+    ...(user.email ? { 'user.email': user.email } : {}),
+  });
+}
+
+export async function startSpan<T>(
+  name: string,
+  op: string,
+  callback: () => T | Promise<T>,
+): Promise<T> {
+  if (!initialized) return callback();
+  return newrelic.startSegment(`${op}:${name}`, true, callback);
+}
+
+export type { MonitorConfig, ErrorContext } from './types.js';

package/dist/integrations/monitor/providers/newrelic/templates/src/monitor/types.ts.template

@@ -0,0 +1,12 @@
+export interface MonitorConfig {
+  enabled: boolean;
+  environment?: string;
+  release?: string;
+  sampleRate?: number;
+}
+
+export interface ErrorContext {
+  user?: { id: string; email?: string };
+  tags?: Record<string, string>;
+  extra?: Record<string, unknown>;
+}

package/dist/integrations/monitor/providers/sentry/templates/src/monitor/index.ts.template

@@ -0,0 +1,70 @@
+import * as Sentry from '@sentry/node';
+import { nodeProfilingIntegration } from '@sentry/profiling-node';
+import type { MonitorConfig, ErrorContext } from './types.js';
+
+let initialized = false;
+
+export function initMonitoring(config?: Partial<MonitorConfig>): boolean {
+  if (initialized) return true;
+
+  const dsn = process.env.SENTRY_DSN;
+  if (!dsn) {
+    console.warn('[monitor] SENTRY_DSN not set — monitoring disabled');
+    return false;
+  }
+
+  Sentry.init({
+    dsn,
+    environment: config?.environment ?? process.env.NODE_ENV ?? 'development',
+    release: config?.release,
+    tracesSampleRate: config?.sampleRate ?? 1.0,
+    profilesSampleRate: config?.sampleRate ?? 1.0,
+    integrations: [nodeProfilingIntegration()],
+  });
+
+  initialized = true;
+  return true;
+}
+
+export function captureError(error: Error, context?: ErrorContext): void {
+  if (!initialized) return;
+
+  Sentry.withScope((scope) => {
+    if (context?.user) scope.setUser(context.user);
+    if (context?.tags) {
+      for (const [key, value] of Object.entries(context.tags)) {
+        scope.setTag(key, value);
+      }
+    }
+    if (context?.extra) {
+      for (const [key, value] of Object.entries(context.extra)) {
+        scope.setExtra(key, value);
+      }
+    }
+    Sentry.captureException(error);
+  });
+}
+
+export function captureMessage(
+  message: string,
+  level: 'info' | 'warning' | 'error' = 'info',
+): void {
+  if (!initialized) return;
+  Sentry.captureMessage(message, level);
+}
+
+export function setUser(user: { id: string; email?: string }): void {
+  if (!initialized) return;
+  Sentry.setUser(user);
+}
+
+export async function startSpan<T>(
+  name: string,
+  op: string,
+  callback: () => T | Promise<T>,
+): Promise<T> {
+  if (!initialized) return callback();
+  return Sentry.startSpan({ name, op }, callback);
+}
+
+export type { MonitorConfig, ErrorContext } from './types.js';

package/dist/integrations/monitor/providers/sentry/templates/src/monitor/types.ts.template

@@ -0,0 +1,12 @@
+export interface MonitorConfig {
+  enabled: boolean;
+  environment?: string;
+  release?: string;
+  sampleRate?: number;
+}
+
+export interface ErrorContext {
+  user?: { id: string; email?: string };
+  tags?: Record<string, string>;
+  extra?: Record<string, unknown>;
+}

package/dist/integrations/queue/providers/bullmq/templates/src/queue/index.ts.template

@@ -0,0 +1,56 @@
+import { Queue, Worker, type Job } from 'bullmq';
+import IORedis from 'ioredis';
+import type { JobOptions, JobHandler } from './types.js';
+
+const connection = new IORedis(process.env.REDIS_URL || 'redis://localhost:6379', {
+  maxRetriesPerRequest: null, // Required by BullMQ
+});
+
+const queues = new Map<string, Queue>();
+const workers = new Map<string, Worker>();
+
+export function createQueue(name: string): Queue {
+  if (queues.has(name)) return queues.get(name)!;
+  const queue = new Queue(name, { connection });
+  queues.set(name, queue);
+  return queue;
+}
+
+export function createWorker<T = unknown>(
+  name: string,
+  handler: JobHandler<T>,
+): Worker {
+  if (workers.has(name)) return workers.get(name)!;
+  const worker = new Worker(
+    name,
+    async (job: Job<T>) => handler(job.data),
+    { connection },
+  );
+  workers.set(name, worker);
+  return worker;
+}
+
+export async function addJob<T = unknown>(
+  queue: Queue,
+  name: string,
+  data: T,
+  options?: JobOptions,
+): Promise<Job<T>> {
+  return queue.add(name, data, {
+    delay: options?.delay,
+    attempts: options?.attempts ?? 3,
+    backoff: options?.backoff ? { type: 'fixed', delay: options.backoff } : undefined,
+    priority: options?.priority,
+  });
+}
+
+export async function closeAll(): Promise<void> {
+  await Promise.all([
+    ...Array.from(queues.values()).map((q) => q.close()),
+    ...Array.from(workers.values()).map((w) => w.close()),
+  ]);
+  queues.clear();
+  workers.clear();
+}
+
+export type { JobOptions, JobHandler } from './types.js';

package/dist/integrations/queue/providers/bullmq/templates/src/queue/types.ts.template

@@ -0,0 +1,10 @@
+export interface JobOptions {
+  delay?: number;     // ms before job becomes processable
+  attempts?: number;  // max retry attempts (default: 3)
+  backoff?: number;   // ms between retries
+  priority?: number;  // lower = higher priority
+}
+
+export interface JobHandler<T = unknown> {
+  (data: T): Promise<void>;
+}