@mettlecast/domain-cli 0.2.0

package/src/utils/s3-fetch.ts

@@ -0,0 +1,91 @@
+import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { createHash } from 'crypto';
+import { Readable } from 'stream';
+
+export interface ModulesJson {
+  scaffoldVersion: string;
+  releasedAt: string;
+  modules: S3ModuleEntry[];
+  compatibility: {
+    cliMinVersion: string;
+    nodeMinVersion: string;
+  };
+}
+
+export interface S3ModuleEntry {
+  id: string;
+  version: string;
+  description: string;
+  dependencies: string[];
+  tarball: string;
+  sha256: string;
+}
+
+export interface VersionsJson {
+  latest: string;
+  versions: string[];
+}
+
+export async function fetchVersionsJson(bucket: string): Promise<VersionsJson> {
+  const client = new S3Client({});
+  const cmd = new GetObjectCommand({ Bucket: bucket, Key: 'versions.json' });
+  const res = await client.send(cmd);
+  const body = await streamToBuffer(res.Body as Readable);
+  return JSON.parse(body.toString('utf-8')) as VersionsJson;
+}
+
+export async function fetchModulesJson(bucket: string, version: string): Promise<ModulesJson> {
+  const client = new S3Client({});
+  const cmd = new GetObjectCommand({
+    Bucket: bucket,
+    Key: `versions/${version}/modules.json`,
+  });
+  const res = await client.send(cmd);
+  const body = await streamToBuffer(res.Body as Readable);
+  return JSON.parse(body.toString('utf-8')) as ModulesJson;
+}
+
+export async function fetchModuleTarball(
+  bucket: string,
+  version: string,
+  tarball: string,
+  expectedSha256: string
+): Promise<Buffer> {
+  const client = new S3Client({});
+  const key = `versions/${version}/${tarball}`;
+  const cmd = new GetObjectCommand({ Bucket: bucket, Key: key });
+  const res = await client.send(cmd);
+  const buf = await streamToBuffer(res.Body as Readable);
+  const actual = createHash('sha256').update(buf).digest('hex');
+  if (actual !== expectedSha256) {
+    throw new Error(
+      `Checksum mismatch for ${tarball}: expected ${expectedSha256}, got ${actual}`
+    );
+  }
+  return buf;
+}
+
+export async function fetchScaffoldFile(
+  bucket: string,
+  version: string,
+  path: string
+): Promise<string | null> {
+  const client = new S3Client({});
+  const cmd = new GetObjectCommand({ Bucket: bucket, Key: `versions/${version}/${path}` });
+  try {
+    const res = await client.send(cmd);
+    const body = await streamToBuffer(res.Body as Readable);
+    return body.toString('utf-8');
+  } catch (err: unknown) {
+    if ((err as { name?: string }).name === 'NoSuchKey') return null;
+    throw err;
+  }
+}
+
+async function streamToBuffer(stream: Readable): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as ArrayBuffer));
+  }
+  return Buffer.concat(chunks);
+}

package/src/utils/scaffold-config.ts

@@ -0,0 +1,172 @@
+import { readFile, writeFile } from 'fs/promises';
+import path from 'path';
+
+export type ModuleId =
+  | 'core'
+  | 'backend-lambda'
+  | 'db-aurora'
+  | 'auth-cognito'
+  | 'frontend'
+  | 'flows'
+  | 'data-management';
+
+export type LogRetentionDays = 30 | 90 | 365 | 2557;
+
+export interface SecurityOptions {
+  /** Enable CMK (KMS customer-managed keys) for DynamoDB, S3, SQS. ~$10–20/month */
+  cmk: boolean;
+  /** Enable GuardDuty threat detection with S3 protection. ~$15–25/month */
+  guardDuty: boolean;
+  /** Enable WAF WebACL on all domain API Gateways. ~$25–60/month */
+  waf: boolean;
+  /** Enable VPC interface endpoints for SM, SQS, EventBridge, Lambda. ~$85–100/month */
+  vpcInterfaceEndpoints: boolean;
+  /** Enable CloudWatch alarms and DLQ depth alarms per domain. ~$10–15/month */
+  cloudWatchAlarms: boolean;
+  /** Enable Cognito advanced security (adaptive auth + compromised-credential detection). Phase B. */
+  cognitoAdvancedSecurity?: boolean;
+  /** Cognito MFA enforcement level. Phase B. */
+  cognitoMfaEnforcement?: 'off' | 'optional' | 'required';
+  /** Secrets Manager auto-rotation cadence in days. 0 = disabled. Phase B. */
+  secretsRotationDays?: 0 | 30 | 90 | 365;
+  /** API Gateway minimum TLS version. Phase B. */
+  tlsMinimumVersion?: '1.2' | '1.3';
+}
+
+/** Cost / performance tunables — Phase B. Schema only in Phase A. */
+export interface CostOptions {
+  auroraMinAcuNonProd?: 0 | 0.5 | 1;
+  auroraPerformanceInsights?: boolean;
+  apiGatewayAccessLogSamplingRate?: 0 | 0.1 | 1.0;
+  lambdaLogLevelDefault?: 'INFO' | 'WARN' | 'ERROR';
+  xRaySamplingRate?: number;
+  reservedConcurrencyPerDomain?: Record<string, number>;
+}
+
+/** Lifecycle tunables — Phase B. Schema only in Phase A. */
+export interface LifecycleOptions {
+  dlqRetentionDays?: 7 | 14;
+  auroraBackupRetentionDays?: 7 | 14 | 35;
+  auditLogArchiveToS3?: boolean;
+}
+
+/** Per-environment URL configuration. */
+export interface EnvironmentConfig {
+  /**
+   * Bare domain for the dashboard in this environment (no scheme, no path, no port).
+   * Example: "app.acme.com". When set, an ACM cert is provisioned and CloudFront is
+   * configured with this domain name. DNS records are surfaced in the Setup tab.
+   */
+  dashboardUrl?: string;
+}
+
+/** Optional per-environment URL overrides. */
+export interface EnvironmentsConfig {
+  dev?: EnvironmentConfig;
+  staging?: EnvironmentConfig;
+  prod?: EnvironmentConfig;
+}
+
+export interface ScaffoldConfig {
+  $schema?: string;
+  /** Scaffold version this project was created with / last upgraded to */
+  scaffoldVersion: string;
+  /** Modules installed in this project */
+  enabledModules: ModuleId[];
+  /** Project identity — used for token substitution and resource naming */
+  projectName: string;
+  awsRegion: string;
+  awsAccountId: string;
+  /** Admin email collected at scaffold time (Cognito seed user). Present only when auth-cognito module is enabled. */
+  adminEmail?: string;
+  /** Domain IDs added via `tib add-domain` — NOT scaffold-owned, user-managed */
+  domainIds: string[];
+  /** Flow IDs added via `tib add-flow` — user-managed */
+  flowIds: string[];
+  /** S3 bucket used for scaffold fetches (defaults to public TIB bucket) */
+  scaffoldBucket: string;
+  /** Security feature opt-ins. All default false. */
+  securityOptions?: SecurityOptions;
+  /** ISO timestamp when scaffold was first deployed per environment. CMK and VPC endpoints are locked after first deploy. */
+  firstDeployedAt?: { dev?: string; prod?: string };
+  /** CloudWatch log retention in days. Default: 30. */
+  logRetentionDays?: LogRetentionDays;
+  /** Cost / performance tunables. Phase B — schema present, CDK not yet wired. */
+  costOptions?: CostOptions;
+  /** Lifecycle tunables. Phase B — schema present, CDK not yet wired. */
+  lifecycleOptions?: LifecycleOptions;
+  /** Per-environment URL configuration for custom domains. */
+  environments?: EnvironmentsConfig;
+  /** When true, CORS responses include Allow-Credentials: true (requires non-wildcard origins). */
+  allowCredentials?: boolean;
+}
+
+const DEFAULT_SCAFFOLD_CONFIG: Omit<ScaffoldConfig, 'domainIds' | 'flowIds'> = {
+  scaffoldVersion: '0.0.0',
+  enabledModules: ['core', 'backend-lambda'],
+  projectName: 'unknown',
+  awsRegion: 'eu-north-1',
+  awsAccountId: '',
+  scaffoldBucket: 'mc-scaffold',
+  securityOptions: {
+    cmk: false,
+    guardDuty: false,
+    waf: false,
+    vpcInterfaceEndpoints: false,
+    cloudWatchAlarms: false,
+  },
+  firstDeployedAt: {},
+  logRetentionDays: 30,
+};
+
+const CONFIG_PATH = '.mc/scaffold-config.json';
+
+export async function readScaffoldConfig(projectRoot: string): Promise<ScaffoldConfig> {
+  const configPath = path.join(projectRoot, CONFIG_PATH);
+  const content = await readFile(configPath, 'utf-8');
+  const raw = JSON.parse(content) as Partial<ScaffoldConfig>;
+
+  // Backward compatibility: old files may only have domainIds/flowIds
+  if (!raw.scaffoldVersion) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[tib] scaffold-config.json is missing scaffoldVersion — project was created before S3 scaffold migration. Run `tib upgrade` to backfill.'
+    );
+  }
+
+  return {
+    ...DEFAULT_SCAFFOLD_CONFIG,
+    domainIds: [],
+    flowIds: [],
+    ...raw,
+  } as ScaffoldConfig;
+}
+
+export async function writeScaffoldConfig(
+  projectRoot: string,
+  config: ScaffoldConfig
+): Promise<void> {
+  const configPath = path.join(projectRoot, CONFIG_PATH);
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+export function updateScaffoldConfig(
+  config: ScaffoldConfig,
+  updates: Partial<ScaffoldConfig>
+): ScaffoldConfig {
+  return { ...config, ...updates };
+}
+
+/**
+ * Add a domain ID to the scaffold config file on disk.
+ */
+export async function addDomainToScaffoldConfig(
+  domainId: string,
+  projectRoot: string
+): Promise<void> {
+  const config = await readScaffoldConfig(projectRoot);
+  if (!config.domainIds.includes(domainId)) {
+    config.domainIds.push(domainId);
+    await writeScaffoldConfig(projectRoot, config);
+  }
+}

package/src/utils/token-substitution.ts

@@ -0,0 +1,80 @@
+export interface TokenContext {
+  PROJECT_NAME: string;
+  PROJECT_NAME_PASCAL: string;
+  PROJECT_NAME_UPPER: string;
+  AWS_REGION: string;
+  AWS_ACCOUNT_ID: string;
+  ADMIN_EMAIL: string;
+  SCAFFOLD_VERSION: string;
+  SCAFFOLD_DATE: string;
+  TIB_CLI_VERSION: string;
+}
+
+export interface ScaffoldConfigForTokens {
+  projectName: string;
+  awsRegion: string;
+  awsAccountId: string;
+  adminEmail?: string;
+}
+
+/**
+ * Replace all {{TOKEN}} placeholders in a template string with values from ctx.
+ * Throws if an unknown token is encountered.
+ */
+export function applyTokens(template: string, ctx: TokenContext): string {
+  return template.replace(/\{\{([A-Z_]+)\}\}/g, (match, key: string) => {
+    const value = (ctx as unknown as Record<string, string>)[key];
+    if (value === undefined) {
+      throw new Error(`Unknown scaffold token: {{${key}}}`);
+    }
+    return value;
+  });
+}
+
+/**
+ * Build a TokenContext from a scaffold config and resolved version.
+ */
+export function buildTokenContext(
+  config: ScaffoldConfigForTokens,
+  scaffoldVersion: string,
+  cliVersion: string
+): TokenContext {
+  const name = config.projectName;
+  return {
+    PROJECT_NAME: name,
+    PROJECT_NAME_PASCAL: toPascalCase(name),
+    PROJECT_NAME_UPPER: toUpperSnakeCase(name),
+    AWS_REGION: config.awsRegion,
+    AWS_ACCOUNT_ID: config.awsAccountId,
+    ADMIN_EMAIL: config.adminEmail ?? '',
+    SCAFFOLD_VERSION: scaffoldVersion,
+    SCAFFOLD_DATE: new Date().toISOString().split('T')[0],
+    TIB_CLI_VERSION: cliVersion,
+  };
+}
+
+function toPascalCase(kebab: string): string {
+  return kebab
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+function toUpperSnakeCase(kebab: string): string {
+  return kebab.replace(/-/g, '_').toUpperCase();
+}
+
+/**
+ * Returns true if the given file extension indicates the file should receive token substitution.
+ * Only .tpl files are substituted.
+ */
+export function isTemplateFile(filename: string): boolean {
+  return filename.endsWith('.tpl');
+}
+
+/**
+ * Strip the .tpl extension from a filename to get the install path.
+ */
+export function stripTplExtension(filename: string): string {
+  return filename.endsWith('.tpl') ? filename.slice(0, -4) : filename;
+}

package/src/utils/zod-extractor.ts

@@ -0,0 +1,31 @@
+/**
+ * Utilities for extracting Zod schemas to JSON Schema format.
+ * Uses zod-to-json-schema to convert live Zod objects to JSON-serializable schema.
+ */
+
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+/**
+ * Extract a Zod schema to its JSON Schema representation.
+ * @param schema - A Zod schema object (e.g., z.object({...})).
+ * @returns JSON Schema object or null if extraction fails.
+ */
+export function extractZodSchema(schema: unknown): Record<string, unknown> | null {
+  if (!schema || typeof schema !== 'object') {
+    return null;
+  }
+
+  try {
+    // Check if this looks like a Zod schema by inspecting for the parse method
+    if (typeof (schema as { parse?: unknown }).parse === 'function') {
+      // Use type assertion to bypass TypeScript compatibility issues with zod versions
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const jsonSchema = zodToJsonSchema(schema as any);
+      return jsonSchema as Record<string, unknown>;
+    }
+  } catch {
+    // Silently return null if extraction fails
+  }
+
+  return null;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "noEmit": false,
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/__tests__/**", "src/templates/**", "node_modules", "dist"]
+}