@mettlecast/domain-cli 0.2.0

package/dist/utils/header-inject.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Inject the @mc-scaffold ownership header into file content.
+ * The header format depends on the file type.
+ * For JSON files in the skip list, returns content unchanged.
+ *
+ * @param content  The file content (post-token-substitution)
+ * @param filename The destination filename (used to determine type)
+ * @param moduleId The scaffold module id (e.g. 'backend-lambda')
+ * @param version  The scaffold module version (e.g. '1.0.0')
+ */
+export declare function injectHeader(content: string, filename: string, moduleId: string, version: string): string;
+/**
+ * Strip the @mc-scaffold header from file content (used during upgrade conflict detection).
+ */
+export declare function stripHeader(content: string, filename: string): string;

package/dist/utils/header-inject.js

@@ -0,0 +1,93 @@
+import path from 'path';
+// Files where adding a key/comment would break schema validation — tracked via manifest only
+const JSON_SKIP_LIST = new Set([
+    'package.json',
+    'tsconfig.json',
+    'tsconfig.base.json',
+]);
+/**
+ * Inject the @mc-scaffold ownership header into file content.
+ * The header format depends on the file type.
+ * For JSON files in the skip list, returns content unchanged.
+ *
+ * @param content  The file content (post-token-substitution)
+ * @param filename The destination filename (used to determine type)
+ * @param moduleId The scaffold module id (e.g. 'backend-lambda')
+ * @param version  The scaffold module version (e.g. '1.0.0')
+ */
+export function injectHeader(content, filename, moduleId, version) {
+    const basename = path.basename(filename);
+    const ext = path.extname(filename).toLowerCase();
+    if (basename.endsWith('.fixture.json')) {
+        return content;
+    }
+    if (ext === '.json') {
+        if (JSON_SKIP_LIST.has(basename)) {
+            return content;
+        }
+        return injectJsonHeader(content, moduleId, version);
+    }
+    if (ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx' || ext === '.mjs') {
+        return injectLineCommentHeader(content, '//', moduleId, version);
+    }
+    if (ext === '.yml' || ext === '.yaml') {
+        return injectLineCommentHeader(content, '#', moduleId, version);
+    }
+    if (ext === '.css' || ext === '.scss') {
+        return injectBlockCommentHeader(content, '/*', '*/', moduleId, version);
+    }
+    if (ext === '.html') {
+        return injectBlockCommentHeader(content, '<!--', '-->', moduleId, version);
+    }
+    if (ext === '.md') {
+        return content;
+    }
+    return content;
+}
+function injectLineCommentHeader(content, commentChar, moduleId, version) {
+    const header = [
+        `${commentChar} @mc-scaffold: ${moduleId}@${version}`,
+        `${commentChar} This file is managed by TIB scaffold. Manual edits will be flagged during \`tib upgrade\`.`,
+        `${commentChar} To opt out of upgrade management for this file, remove these header lines.`,
+        '',
+    ].join('\n');
+    // Preserve shebang line if present
+    if (content.startsWith('#!')) {
+        const newlineIdx = content.indexOf('\n');
+        if (newlineIdx === -1)
+            return content + '\n' + header;
+        return content.slice(0, newlineIdx + 1) + header + content.slice(newlineIdx + 1);
+    }
+    return header + content;
+}
+function injectBlockCommentHeader(content, open, close, moduleId, version) {
+    const header = [
+        `${open} @mc-scaffold: ${moduleId}@${version} ${close}`,
+        `${open} This file is managed by TIB scaffold. Manual edits will be flagged during \`tib upgrade\`. ${close}`,
+        '',
+    ].join('\n');
+    return header + content;
+}
+function injectJsonHeader(content, moduleId, version) {
+    try {
+        const parsed = JSON.parse(content);
+        const withHeader = { _tibScaffold: `${moduleId}@${version}`, ...parsed };
+        return JSON.stringify(withHeader, null, 2);
+    }
+    catch {
+        return content;
+    }
+}
+/**
+ * Strip the @mc-scaffold header from file content (used during upgrade conflict detection).
+ */
+export function stripHeader(content, filename) {
+    const ext = path.extname(filename).toLowerCase();
+    if (ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx' || ext === '.mjs') {
+        return content.replace(/^\/\/ @mc-scaffold:.*\n\/\/ This file is.*\n\/\/ To opt out.*\n\n?/, '');
+    }
+    if (ext === '.yml' || ext === '.yaml') {
+        return content.replace(/^# @mc-scaffold:.*\n# This file is.*\n\n?/, '');
+    }
+    return content;
+}

package/dist/utils/install-file.d.ts

@@ -0,0 +1,17 @@
+import type { ManifestFileEntry } from './manifest.js';
+export type FilePolicy = 'owned' | 'tracked' | 'seed';
+export interface InstallResult {
+    status: 'added' | 'updated' | 'conflict' | 'skipped' | 'unchanged';
+}
+/**
+ * Install a scaffold file according to its policy.
+ *
+ * - owned: always overwrite. Return 'added' if new, 'updated' if existed.
+ * - tracked: check sha256. If same → 'unchanged'. If different, check disk for drift.
+ *   If drifted → write .tib-upgrade file → 'conflict'. If not drifted → overwrite → 'updated'.
+ *   If no currentEntry → write new → 'added'.
+ * - seed: if file exists → 'skipped'. Else write → 'added'.
+ */
+export declare function installScaffoldFile(absPath: string, content: string, policy: FilePolicy, currentEntry: ManifestFileEntry | undefined, opts?: {
+    dryRun?: boolean;
+}): Promise<InstallResult>;

package/dist/utils/install-file.js

@@ -0,0 +1,78 @@
+import { writeFile, mkdir, access } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { computeChecksumString, computeChecksumFile } from './checksum.js';
+/**
+ * Install a scaffold file according to its policy.
+ *
+ * - owned: always overwrite. Return 'added' if new, 'updated' if existed.
+ * - tracked: check sha256. If same → 'unchanged'. If different, check disk for drift.
+ *   If drifted → write .tib-upgrade file → 'conflict'. If not drifted → overwrite → 'updated'.
+ *   If no currentEntry → write new → 'added'.
+ * - seed: if file exists → 'skipped'. Else write → 'added'.
+ */
+export async function installScaffoldFile(absPath, content, policy, currentEntry, opts) {
+    const dryRun = opts?.dryRun ?? false;
+    const newChecksum = computeChecksumString(content);
+    // Helper to check if file exists
+    const fileExists = async (path) => {
+        try {
+            await access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (policy === 'owned') {
+        // owned: always overwrite, no sha256 check
+        const exists = await fileExists(absPath);
+        if (!dryRun) {
+            await mkdir(dirname(absPath), { recursive: true });
+            await writeFile(absPath, content, 'utf-8');
+        }
+        return { status: exists ? 'updated' : 'added' };
+    }
+    if (policy === 'seed') {
+        // seed: never overwrite existing file
+        const exists = await fileExists(absPath);
+        if (exists) {
+            return { status: 'skipped' };
+        }
+        if (!dryRun) {
+            await mkdir(dirname(absPath), { recursive: true });
+            await writeFile(absPath, content, 'utf-8');
+        }
+        return { status: 'added' };
+    }
+    // policy === 'tracked'
+    if (!currentEntry) {
+        // New file: write it
+        if (!dryRun) {
+            await mkdir(dirname(absPath), { recursive: true });
+            await writeFile(absPath, content, 'utf-8');
+        }
+        return { status: 'added' };
+    }
+    // File exists in manifest: check if content changed
+    if (newChecksum === currentEntry.sha256) {
+        // Content unchanged
+        return { status: 'unchanged' };
+    }
+    // Content changed: check for drift
+    const diskChecksum = await computeChecksumFile(absPath);
+    const drifted = diskChecksum !== null && diskChecksum !== currentEntry.sha256;
+    if (drifted) {
+        // Drift detected: write .tib-upgrade file, don't touch original
+        if (!dryRun) {
+            await mkdir(dirname(absPath), { recursive: true });
+            await writeFile(`${absPath}.tib-upgrade`, content, 'utf-8');
+        }
+        return { status: 'conflict' };
+    }
+    // No drift: safe to overwrite
+    if (!dryRun) {
+        await mkdir(dirname(absPath), { recursive: true });
+        await writeFile(absPath, content, 'utf-8');
+    }
+    return { status: 'updated' };
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,12 @@
+import { type Logger } from 'pino';
+/**
+ * Factory that creates a pino logger with pino-pretty transport for CLI output.
+ * @param name - Optional logger name shown in pino-pretty output. Defaults to 'tib-domain'.
+ * @returns A pino Logger instance configured for human-readable terminal output.
+ */
+export declare function createCliLogger(name?: string): Logger;
+/**
+ * Default singleton CLI logger used by all domain-cli commands.
+ * Pretty-printed with timestamps to stdout.
+ */
+export declare const cliLogger: Logger;

package/dist/utils/logger.js

@@ -0,0 +1,24 @@
+import pino from 'pino';
+/**
+ * Factory that creates a pino logger with pino-pretty transport for CLI output.
+ * @param name - Optional logger name shown in pino-pretty output. Defaults to 'tib-domain'.
+ * @returns A pino Logger instance configured for human-readable terminal output.
+ */
+export function createCliLogger(name = 'tib-domain') {
+    return pino({
+        name,
+        transport: {
+            target: 'pino-pretty',
+            options: {
+                colorize: true,
+                translateTime: 'SYS:HH:MM:ss',
+                ignore: 'pid,hostname',
+            },
+        },
+    });
+}
+/**
+ * Default singleton CLI logger used by all domain-cli commands.
+ * Pretty-printed with timestamps to stdout.
+ */
+export const cliLogger = createCliLogger();

package/dist/utils/manifest.d.ts

@@ -0,0 +1,28 @@
+export type FilePolicy = 'owned' | 'tracked' | 'seed';
+export interface ManifestFileEntry {
+    path: string;
+    module: string;
+    moduleVersion: string;
+    sha256: string;
+    wasTemplate: boolean;
+    installedAt: string;
+    policy: FilePolicy;
+}
+export interface TibManifest {
+    $schema: string;
+    scaffoldVersion: string;
+    createdAt: string;
+    updatedAt: string;
+    projectName: string;
+    awsRegion: string;
+    enabledModules: string[];
+    files: ManifestFileEntry[];
+}
+export declare function inferPolicyFromPath(filePath: string): FilePolicy;
+export declare function readManifest(projectRoot: string): Promise<TibManifest | null>;
+export declare function writeManifest(projectRoot: string, manifest: TibManifest): Promise<void>;
+export declare function createManifest(scaffoldVersion: string, projectName: string, awsRegion: string, enabledModules: string[]): TibManifest;
+export declare function upsertManifestFile(manifest: TibManifest, entry: ManifestFileEntry): void;
+export declare function removeManifestFile(manifest: TibManifest, filePath: string): void;
+export declare function getManifestFile(manifest: TibManifest, filePath: string): ManifestFileEntry | undefined;
+export declare function isScaffoldOwned(manifest: TibManifest, filePath: string): boolean;

package/dist/utils/manifest.js

@@ -0,0 +1,93 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import path from 'path';
+import { cliLogger } from './logger.js';
+const MANIFEST_PATH = '.mc/manifest.json';
+const SCHEMA_URL = 'https://mc-scaffold.s3.amazonaws.com/schema/manifest.v3.json';
+export function inferPolicyFromPath(filePath) {
+    // owned: infra/, .mc/infra/, mc-deploy.yml, .github/workflows/
+    if (filePath.match(/^infra\//) ||
+        filePath.match(/^\.tib\/infra\//) ||
+        filePath === 'mc-deploy.yml' ||
+        filePath.match(/^\.github\/workflows\//)) {
+        return 'owned';
+    }
+    // seed: specific frontend paths
+    const seedPatterns = [
+        /^frontend\/src\/pages\/auth\//,
+        /^frontend\/src\/pages\/account\//,
+        /^frontend\/src\/pages\/shell\//,
+        /^frontend\/src\/pages\/_errors\//,
+        /^frontend\/src\/layouts\//,
+        /^frontend\/src\/styles\/brand\.css$/,
+    ];
+    if (seedPatterns.some((pattern) => pattern.test(filePath))) {
+        return 'seed';
+    }
+    // tracked: everything else
+    return 'tracked';
+}
+export async function readManifest(projectRoot) {
+    const manifestPath = path.join(projectRoot, MANIFEST_PATH);
+    try {
+        const content = await readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(content);
+        // v1→v2 migration: infer policy for entries missing it
+        let needsMigration = false;
+        for (const entry of manifest.files) {
+            if (!entry['policy']) {
+                entry['policy'] = inferPolicyFromPath(entry['path']);
+                needsMigration = true;
+            }
+        }
+        if (needsMigration) {
+            cliLogger.info('manifest: migrating v1→v2 with inferred policies');
+            await writeManifest(projectRoot, manifest);
+        }
+        return manifest;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export async function writeManifest(projectRoot, manifest) {
+    const manifestPath = path.join(projectRoot, MANIFEST_PATH);
+    await mkdir(path.dirname(manifestPath), { recursive: true });
+    manifest.$schema = SCHEMA_URL;
+    manifest.updatedAt = new Date().toISOString();
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+export function createManifest(scaffoldVersion, projectName, awsRegion, enabledModules) {
+    const now = new Date().toISOString();
+    return {
+        $schema: SCHEMA_URL,
+        scaffoldVersion,
+        createdAt: now,
+        updatedAt: now,
+        projectName,
+        awsRegion,
+        enabledModules,
+        files: [],
+    };
+}
+export function upsertManifestFile(manifest, entry) {
+    const idx = manifest.files.findIndex((f) => f.path === entry.path);
+    if (idx === -1) {
+        manifest.files.push(entry);
+    }
+    else {
+        manifest.files[idx] = entry;
+    }
+}
+export function removeManifestFile(manifest, filePath) {
+    manifest.files = manifest.files.filter((f) => f.path !== filePath);
+}
+export function getManifestFile(manifest, filePath) {
+    return manifest.files.find((f) => f.path === filePath);
+}
+export function isScaffoldOwned(manifest, filePath) {
+    const entry = manifest.files.find((f) => f.path === filePath);
+    // Scaffold-managed means in manifest AND policy is not 'seed'
+    return entry != null && entry.policy !== 'seed';
+}

package/dist/utils/s3-fetch.d.ts

@@ -0,0 +1,25 @@
+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 declare function fetchVersionsJson(bucket: string): Promise<VersionsJson>;
+export declare function fetchModulesJson(bucket: string, version: string): Promise<ModulesJson>;
+export declare function fetchModuleTarball(bucket: string, version: string, tarball: string, expectedSha256: string): Promise<Buffer>;
+export declare function fetchScaffoldFile(bucket: string, version: string, path: string): Promise<string | null>;

package/dist/utils/s3-fetch.js

@@ -0,0 +1,52 @@
+import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { createHash } from 'crypto';
+export async function fetchVersionsJson(bucket) {
+    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);
+    return JSON.parse(body.toString('utf-8'));
+}
+export async function fetchModulesJson(bucket, version) {
+    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);
+    return JSON.parse(body.toString('utf-8'));
+}
+export async function fetchModuleTarball(bucket, version, tarball, expectedSha256) {
+    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);
+    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, version, path) {
+    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);
+        return body.toString('utf-8');
+    }
+    catch (err) {
+        if (err.name === 'NoSuchKey')
+            return null;
+        throw err;
+    }
+}
+async function streamToBuffer(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}

package/dist/utils/scaffold-config.d.ts

@@ -0,0 +1,95 @@
+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;
+}
+export declare function readScaffoldConfig(projectRoot: string): Promise<ScaffoldConfig>;
+export declare function writeScaffoldConfig(projectRoot: string, config: ScaffoldConfig): Promise<void>;
+export declare function updateScaffoldConfig(config: ScaffoldConfig, updates: Partial<ScaffoldConfig>): ScaffoldConfig;
+/**
+ * Add a domain ID to the scaffold config file on disk.
+ */
+export declare function addDomainToScaffoldConfig(domainId: string, projectRoot: string): Promise<void>;

package/dist/utils/scaffold-config.js

@@ -0,0 +1,53 @@
+import { readFile, writeFile } from 'fs/promises';
+import path from 'path';
+const DEFAULT_SCAFFOLD_CONFIG = {
+    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) {
+    const configPath = path.join(projectRoot, CONFIG_PATH);
+    const content = await readFile(configPath, 'utf-8');
+    const raw = JSON.parse(content);
+    // 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,
+    };
+}
+export async function writeScaffoldConfig(projectRoot, config) {
+    const configPath = path.join(projectRoot, CONFIG_PATH);
+    await writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+export function updateScaffoldConfig(config, updates) {
+    return { ...config, ...updates };
+}
+/**
+ * Add a domain ID to the scaffold config file on disk.
+ */
+export async function addDomainToScaffoldConfig(domainId, projectRoot) {
+    const config = await readScaffoldConfig(projectRoot);
+    if (!config.domainIds.includes(domainId)) {
+        config.domainIds.push(domainId);
+        await writeScaffoldConfig(projectRoot, config);
+    }
+}

package/dist/utils/token-substitution.d.ts

@@ -0,0 +1,35 @@
+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 declare function applyTokens(template: string, ctx: TokenContext): string;
+/**
+ * Build a TokenContext from a scaffold config and resolved version.
+ */
+export declare function buildTokenContext(config: ScaffoldConfigForTokens, scaffoldVersion: string, cliVersion: string): TokenContext;
+/**
+ * Returns true if the given file extension indicates the file should receive token substitution.
+ * Only .tpl files are substituted.
+ */
+export declare function isTemplateFile(filename: string): boolean;
+/**
+ * Strip the .tpl extension from a filename to get the install path.
+ */
+export declare function stripTplExtension(filename: string): string;