@saasicat/cli 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,548 @@
+import { MfaService, AdminAuditService, AdminManifestService, DiscoverySnapshot, ProviderSpec, DiscoveryScanner } from '@saasicat/nest';
+import { UserPort, PlatformUserDto, AuditQueryPort, AuditEntry, AdminManifest, ManifestAccessPort, PlanCatalog, UserManagementPort } from '@saasicat/types';
+import { Type, DynamicModule } from '@nestjs/common';
+import { CommandRunner } from 'nest-commander';
+
+declare const CLI_CONTEXT_CONFIG_TOKEN: unique symbol;
+declare const USER_PORT_TOKEN: unique symbol;
+/** Write/list operations for the shared `<app> user` command. */
+declare const USER_MANAGEMENT_PORT_TOKEN: unique symbol;
+declare const AUDIT_QUERY_PORT_TOKEN: unique symbol;
+/** List of DoctorCheck implementations — consumers may extend. */
+declare const DOCTOR_CHECKS_TOKEN: unique symbol;
+declare const MANIFEST_ACCESS_PORT_TOKEN: unique symbol;
+/** List of ManifestCheck implementations — consumers may extend. */
+declare const MANIFEST_CHECKS_TOKEN: unique symbol;
+
+interface CliContextConfig {
+    /**
+     * Env-var name for the admin email (e.g. `MYAPP_ADMIN_EMAIL`).
+     * Platform default: `SAAS_ADMIN_EMAIL`.
+     */
+    adminEmailEnvVar: string;
+    /**
+     * Function that returns `true` when the CLI runs against a production
+     * environment. The consumer checks its own env vars (e.g.
+     * `MYAPP_ENV === 'production'`, `DATABASE_URL` host, etc.).
+     */
+    isProductionEnvironment: () => boolean;
+    /**
+     * Env-var name for the MFA-bypass switch (e.g. `MYAPP_SKIP_MFA`).
+     * Platform default: `SAAS_PLATFORM_SKIP_MFA`. The bypass only takes
+     * effect when `isProductionEnvironment()` is `false`.
+     */
+    mfaSkipEnvVar: string;
+    /**
+     * Display issuer for `<app> admin mfa-setup` in the authenticator
+     * (e.g. "DemoApp SuperAdmin", "ClubApp SuperAdmin").
+     * Default: `"SuperAdmin"`.
+     */
+    mfaIssuer?: string;
+}
+interface CliIdentity {
+    email: string;
+    host: string;
+    /** "cli:<email>:<host>" — canonical audit actor tag. */
+    actor: string;
+}
+declare class CliContextService {
+    private readonly config;
+    private readonly users;
+    private readonly mfa;
+    private readonly audit;
+    constructor(config: CliContextConfig, users: UserPort, mfa: MfaService, audit: AdminAuditService);
+    resolveIdentity(asFlag?: string): CliIdentity;
+    /**
+     * Loads + validates the user for a CLI identity:
+     *   - user exists + active
+     *   - user has platform role SUPER_ADMIN
+     *
+     * Throws `CliError(NOT_SUPER_ADMIN, exit=2)` otherwise.
+     */
+    ensureSuperAdmin(identity: CliIdentity): Promise<PlatformUserDto>;
+    /**
+     * Prompts the user for a TOTP code and verifies it against the stored
+     * secret (via the platform `MfaService` → `MfaPort`).
+     *
+     * Bypass: `process.env[mfaSkipEnvVar] === '1'` AND `!isProductionEnvironment()`.
+     */
+    requireMfa(userId: string): Promise<void>;
+    ensureProductionConfirmation(opts?: {
+        yes?: boolean;
+    }): Promise<void>;
+    /**
+     * Writes an audit-log entry with the CLI actor tag. Wrapper over
+     * `AdminAuditService.log` with automatic `fromCli` construction.
+     */
+    log(input: {
+        identity: CliIdentity;
+        userId: string;
+        entity: string;
+        entityId: string;
+        action: string;
+        changes?: Record<string, unknown>;
+    }): Promise<void>;
+    table(rows: Record<string, unknown>[]): void;
+    /**
+     * Reads a line from stdin. Override hook for tests: set
+     * `process.env.SAAS_PLATFORM_CLI_PROMPT_REPLY` to a reply, then
+     * the method succeeds without interaction.
+     */
+    prompt(question: string): Promise<string>;
+}
+/**
+ * Structured CLI error with `exitCode` mapping per
+ * `cli-conventions.md` §6:
+ *
+ *   1 = user error, 2 = auth, 3 = MFA, 4 = connectivity,
+ *   5 = permission, 6 = conflict, 7 = drift, 99 = internal.
+ */
+declare class CliError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    constructor(code: string, message: string, exitCode: number);
+}
+
+interface MfaSetupOptions {
+    /** `--as <email>` override for the actor identity. */
+    asFlag?: string;
+    /**
+     * Issuer string shown in the authenticator (e.g. "DemoApp SuperAdmin",
+     * "ClubApp SuperAdmin"). Consumers set their own app name.
+     */
+    issuer: string;
+    /**
+     * Optional: confirms overwriting an existing secret. Default: the first
+     * re-setup request must be confirmed interactively with `yes`, otherwise
+     * it is aborted.
+     */
+    force?: boolean;
+}
+interface MfaSetupResult {
+    /** Base32-encoded TOTP secret. */
+    secret: string;
+    /** otpauth URI for a QR-code generator (authenticator app). */
+    otpauthUri: string;
+    /** Email + ID of the user whose secret was just created. */
+    userId: string;
+    userEmail: string;
+}
+declare class MfaSetupFlow {
+    private readonly ctx;
+    private readonly mfa;
+    constructor(ctx: CliContextService, mfa: MfaService);
+    /**
+     * Runs the full setup flow. Throws `CliError` subclasses on
+     * auth/identity/confirmation errors.
+     */
+    run(options: MfaSetupOptions): Promise<MfaSetupResult>;
+    /**
+     * Helper: returns a human-readable output block with secret + otpauthUri
+     * for `console.log` in the consumer command. Consumers may prepend their
+     * own QR-code renderer (e.g. `qrcode-terminal`).
+     */
+    formatSetupResult(result: MfaSetupResult): string;
+}
+
+interface WhoAmIResult {
+    email: string;
+    host: string;
+    actor: string;
+    userId: string | null;
+    isSuperAdmin: boolean;
+    mfaEnabled: boolean;
+    isProduction: boolean;
+    mfaSkipActive: boolean;
+}
+declare class WhoAmIFlow {
+    private readonly config;
+    private readonly ctx;
+    private readonly mfa;
+    constructor(config: CliContextConfig, ctx: CliContextService, mfa: MfaService);
+    run(asFlag?: string): Promise<WhoAmIResult>;
+    formatResult(r: WhoAmIResult): string;
+}
+
+interface AuditTailOptions {
+    actor?: string;
+    action?: string;
+    entity?: string;
+    since?: string;
+    /** Default 50, max 500 — enforced by the consumer adapter. */
+    limit?: number;
+}
+declare class AuditTailFlow {
+    private readonly auditQuery;
+    constructor(auditQuery: AuditQueryPort);
+    run(options?: AuditTailOptions): Promise<AuditEntry[]>;
+    /** Format the result as an ASCII table for `console.table`. */
+    formatRows(entries: AuditEntry[]): Record<string, string>[];
+    private truncate;
+}
+
+type CheckSeverity = 'ok' | 'warning' | 'error';
+interface DoctorCheck {
+    /** Unique slug (e.g. "platform.user-port", "demoapp.kosit-sidecar"). */
+    readonly id: string;
+    /** Display text in the output. */
+    readonly label: string;
+    run(): Promise<DoctorCheckResult>;
+}
+interface DoctorCheckResult {
+    severity: CheckSeverity;
+    message: string;
+    /** Optional: detail data for the JSON output. */
+    details?: Record<string, unknown>;
+}
+interface DoctorReport {
+    /** Overall status = max(severity) across all checks. */
+    overall: CheckSeverity;
+    checks: Array<{
+        id: string;
+        label: string;
+        severity: CheckSeverity;
+        message: string;
+        details?: Record<string, unknown>;
+    }>;
+}
+declare class DoctorFlow {
+    private readonly checks;
+    constructor(checks: DoctorCheck[]);
+    run(): Promise<DoctorReport>;
+    /** Returns the appropriate CLI exit code: 0 for `ok`/`warning`, 4 for `error`. */
+    exitCodeFor(report: DoctorReport): number;
+    formatReport(report: DoctorReport): string;
+}
+
+interface ManifestCheckResult {
+    severity: 'ok' | 'warning' | 'error';
+    message: string;
+    /** Optional: affected paths/keys for detailed output. */
+    paths?: string[];
+}
+interface ManifestCheck {
+    readonly id: string;
+    readonly label: string;
+    run(manifest: AdminManifest): ManifestCheckResult;
+}
+declare const DEFAULT_MANIFEST_CHECKS: ManifestCheck[];
+
+interface ManifestCheckReport {
+    overall: 'ok' | 'warning' | 'error';
+    checks: Array<{
+        id: string;
+        label: string;
+        severity: 'ok' | 'warning' | 'error';
+        message: string;
+        paths?: string[];
+    }>;
+}
+declare class ManifestCliFlow {
+    private readonly access;
+    private readonly checks;
+    constructor(access: ManifestAccessPort, checks: ManifestCheck[]);
+    /** `<app> manifest dump` — JSON output of the current manifest. */
+    dump(): AdminManifest;
+    /**
+     * `<app> manifest hash` — canonical manifestHash value. Returns
+     * the value from `build.manifestHash`. Consumers can pin this in CI
+     * (`expected-hash.txt`) and check for drift.
+     */
+    hash(): string;
+    /**
+     * `<app> manifest validate` — returns `true` when all structures
+     * are present. Deeper schema validation runs separately via Ajv with
+     * `@saasicat/spec/schemas/admin-manifest.schema.json`;
+     * this helper provides the quick diagnostic without the Ajv cost.
+     */
+    validate(): {
+        ok: boolean;
+        reason?: string;
+    };
+    /**
+     * `<app> manifest diff <expected.json>` — flat diff over the two
+     * manifest hashes plus list differences for top-level fields. Returns
+     * `null` when the manifests are identical.
+     */
+    diff(expected: AdminManifest): ManifestDiff | null;
+    /**
+     * `<app> manifest check` — runs all registered manifest checks.
+     * Aggregates severity (ok/warning/error) into `overall`. The consumer
+     * maps `error` to exit code 7 (drift) per `cli-conventions.md` §6.
+     */
+    runChecks(): Promise<ManifestCheckReport>;
+    /** Returns the appropriate CLI exit code: 0 for `ok`/`warning`, 7 for `error` (drift). */
+    exitCodeFor(report: ManifestCheckReport): number;
+    formatReport(report: ManifestCheckReport): string;
+}
+interface ManifestDiff {
+    currentHash: string | null;
+    expectedHash: string | null;
+    componentKeysAdded: string[];
+    componentKeysRemoved: string[];
+}
+
+declare class PlanCatalogDoctorCheck implements DoctorCheck {
+    private readonly catalog;
+    readonly id = "platform.plan-catalog";
+    readonly label = "Plan-Catalog im DI";
+    constructor(catalog: PlanCatalog);
+    run(): Promise<DoctorCheckResult>;
+}
+declare class DiscoverySnapshotDoctorCheck implements DoctorCheck {
+    private readonly snapshot;
+    readonly id = "platform.discovery-snapshot";
+    readonly label = "Discovery-Snapshot beim Boot";
+    constructor(snapshot: DiscoverySnapshot);
+    run(): Promise<DoctorCheckResult>;
+}
+declare class UserPortDoctorCheck implements DoctorCheck {
+    private readonly users;
+    readonly id = "platform.user-port";
+    readonly label = "UserPort.findByEmail erreichbar";
+    constructor(users: UserPort);
+    run(): Promise<DoctorCheckResult>;
+}
+declare class AdminManifestDoctorCheck implements DoctorCheck {
+    private readonly manifest;
+    readonly id = "platform.admin-manifest";
+    readonly label = "AdminManifestService liefert Manifest";
+    constructor(manifest: AdminManifestService);
+    run(): Promise<DoctorCheckResult>;
+}
+/**
+ * Default list that consumers can spread in `CliContextModule.forRoot({ doctorChecks })`:
+ *
+ * ```ts
+ * doctorChecks: [
+ *     ...DEFAULT_DOCTOR_CHECKS,
+ *     new MyAppKositReachableCheck(),
+ * ],
+ * ```
+ *
+ * Platform checks need DI providers — they are instantiated automatically by
+ * `CliContextModule` as `extraProviders` when the app sets
+ * `defaultDoctorChecks: true`.
+ */
+declare const PLATFORM_DOCTOR_CHECK_PROVIDERS: Array<Type<DoctorCheck>>;
+
+/** Returns the names of all top-level `model X { ... }` blocks in the schema. */
+declare function extractModelNames(schema: string): string[];
+/**
+ * Returns all `model X { ... }` blocks from a fragment as a map
+ * `name -> complete block text incl. opening/closing braces`.
+ *
+ * Delimiting logic: we search for `^model X {` (start of line, possibly with
+ * leading whitespace) and close as soon as the brace depth drops back to
+ * 0. Strings/comments inside the block are, in simplified terms, not
+ * counted, which is robust for Prisma schemas (no curly braces
+ * in strings, comments only `//`-style).
+ */
+declare function extractModelBlocks(fragment: string): Map<string, string>;
+interface ApplyResult {
+    /** Number of models that were added. */
+    added: string[];
+    /** Number of models that were already present (no write). */
+    skipped: string[];
+    /** Resulting schema text. When `added.length === 0` identical to the input. */
+    schema: string;
+}
+/**
+ * Appends missing models from `fragmentBlocks` to the end of `schema`. Existing
+ * models (same name) stay unchanged and are listed in `skipped`.
+ */
+declare function applyFragmentBlocks(schema: string, fragmentBlocks: Map<string, string>, options?: {
+    fragmentLabel?: string;
+}): ApplyResult;
+
+interface CliContextModuleOptions {
+    config: CliContextConfig;
+    userPort: ProviderSpec<UserPort>;
+    /**
+     * Optional: audit query port for `AuditTailFlow`. If not set,
+     * `AuditTailFlow` rejects with a DI error — `<app> audit tail` is then
+     * not available.
+     */
+    auditQueryPort?: ProviderSpec<AuditQueryPort>;
+    /**
+     * Optional: list of DoctorChecks for `DoctorFlow`. Default: empty
+     * — `<app> doctor` runs but returns no content. Consumers register
+     * project-specific checks.
+     *
+     * Note: if `defaultDoctorChecks: true`, the 4 platform standard checks
+     * (PlanCatalog/Discovery/UserPort/AdminManifest) are registered **in
+     * addition** to this list.
+     */
+    doctorChecks?: ProviderSpec<DoctorCheck[]>;
+    /**
+     * Default `false`. If `true`, the platform registers the four standard
+     * checks from `PLATFORM_DOCTOR_CHECK_PROVIDERS` in addition to
+     * `doctorChecks`. Recommended for all apps that take `<app> doctor` seriously.
+     */
+    defaultDoctorChecks?: boolean;
+    /**
+     * Optional: ManifestAccessPort for `<app> manifest dump|hash|check|...`.
+     * If not set, `ManifestCliFlow` is not registered.
+     */
+    manifestAccessPort?: ProviderSpec<ManifestAccessPort>;
+    /**
+     * Optional: full ManifestChecks list. Default is the 10
+     * `DEFAULT_MANIFEST_CHECKS`. Consumer extensions should pass through
+     * `[...DEFAULT_MANIFEST_CHECKS, ...projectSpecific]`.
+     */
+    manifestChecks?: ProviderSpec<ManifestCheck[]>;
+    /**
+     * Optional: UserManagementPort for the shared `<app> user` command
+     * (create-super-admin/reassign-admin/list/reset-password/deactivate).
+     * Without this port `UserCommands` cannot be resolved — register the
+     * command only if this port is set.
+     */
+    userManagementPort?: ProviderSpec<UserManagementPort>;
+    /** Register the module globally — default `false`. */
+    global?: boolean;
+}
+declare class CliContextModule {
+    static forRoot(options: CliContextModuleOptions): DynamicModule;
+}
+
+interface AsFlag$2 {
+    as?: string;
+}
+declare class ManifestDumpCommand extends CommandRunner {
+    private readonly ctx;
+    private readonly flow;
+    constructor(ctx: CliContextService, flow: ManifestCliFlow);
+    run(_args: string[], flags: AsFlag$2): Promise<void>;
+    parseAs(v: string): string;
+}
+declare class ManifestHashCommand extends CommandRunner {
+    private readonly ctx;
+    private readonly flow;
+    constructor(ctx: CliContextService, flow: ManifestCliFlow);
+    run(_args: string[], flags: AsFlag$2): Promise<void>;
+    parseAs(v: string): string;
+}
+declare class ManifestValidateCommand extends CommandRunner {
+    private readonly ctx;
+    private readonly flow;
+    constructor(ctx: CliContextService, flow: ManifestCliFlow);
+    run(_args: string[], flags: AsFlag$2): Promise<void>;
+    parseAs(v: string): string;
+}
+declare class ManifestCheckCommand extends CommandRunner {
+    private readonly ctx;
+    private readonly flow;
+    constructor(ctx: CliContextService, flow: ManifestCliFlow);
+    run(_args: string[], flags: AsFlag$2): Promise<void>;
+    parseAs(v: string): string;
+}
+declare class ManifestCommands extends CommandRunner {
+    run(): Promise<void>;
+}
+
+interface AsFlag$1 {
+    as?: string;
+}
+interface MfaSetupFlags extends AsFlag$1 {
+    force?: boolean;
+}
+declare class AdminWhoamiCommand extends CommandRunner {
+    private readonly flow;
+    constructor(flow: WhoAmIFlow);
+    run(_args: string[], flags: AsFlag$1): Promise<void>;
+    parseAs(v: string): string;
+}
+declare class AdminMfaSetupCommand extends CommandRunner {
+    private readonly config;
+    private readonly flow;
+    constructor(config: CliContextConfig, flow: MfaSetupFlow);
+    run(_args: string[], flags: MfaSetupFlags): Promise<void>;
+    parseAs(v: string): string;
+    parseForce(): boolean;
+}
+declare class AdminCommands extends CommandRunner {
+    run(): Promise<void>;
+}
+
+interface TailFlags {
+    as?: string;
+    actor?: string;
+    action?: string;
+    entity?: string;
+    since?: string;
+    limit?: number;
+}
+declare class AuditTailCommand extends CommandRunner {
+    private readonly ctx;
+    private readonly flow;
+    constructor(ctx: CliContextService, flow: AuditTailFlow);
+    run(_args: string[], flags: TailFlags): Promise<void>;
+    parseAs(v: string): string;
+    parseActor(v: string): string;
+    parseAction(v: string): string;
+    parseEntity(v: string): string;
+    parseSince(v: string): string;
+    parseLimit(v: string): number;
+}
+declare class AuditCommands extends CommandRunner {
+    run(): Promise<void>;
+}
+
+interface AsFlag {
+    as?: string;
+}
+declare class DoctorCommands extends CommandRunner {
+    private readonly ctx;
+    private readonly flow;
+    constructor(ctx: CliContextService, flow: DoctorFlow);
+    run(_args: string[], flags: AsFlag): Promise<void>;
+    parseAs(v: string): string;
+}
+
+interface ScanFlags {
+    out?: string;
+    nonFatal?: boolean;
+}
+declare class DiscoveryScanCommand extends CommandRunner {
+    private readonly scanner;
+    private readonly configuredPath;
+    constructor(scanner?: DiscoveryScanner | null, configuredPath?: string | null);
+    run(_args: string[], flags: ScanFlags): Promise<void>;
+    /** Exit 4 (analogous to Seed-Gate/Preflight) — only a warning with `--non-fatal`. */
+    private fail;
+    parseOut(v: string): string;
+    parseNonFatal(): boolean;
+}
+declare class DiscoveryCommands extends CommandRunner {
+    run(): Promise<void>;
+}
+
+interface UserFlags {
+    as?: string;
+    to?: string;
+    reason?: string;
+    yes?: boolean;
+    first?: string;
+    last?: string;
+    password?: string;
+}
+declare class UserCommands extends CommandRunner {
+    private readonly ctx;
+    private readonly users;
+    constructor(ctx: CliContextService, users: UserManagementPort);
+    run(args: string[], flags: UserFlags): Promise<void>;
+    private createSuperAdmin;
+    private reassignAdmin;
+    private list;
+    private resetPassword;
+    private deactivate;
+    parseAs(val: string): string;
+    parseTo(val: string): string;
+    parseReason(val: string): string;
+    parseYes(): boolean;
+    parseFirst(val: string): string;
+    parseLast(val: string): string;
+    parsePassword(val: string): string;
+}
+
+export { AUDIT_QUERY_PORT_TOKEN, AdminCommands, AdminManifestDoctorCheck, AdminMfaSetupCommand, AdminWhoamiCommand, type ApplyResult, AuditCommands, AuditTailCommand, AuditTailFlow, type AuditTailOptions, CLI_CONTEXT_CONFIG_TOKEN, type CheckSeverity, type CliContextConfig, CliContextModule, type CliContextModuleOptions, CliContextService, CliError, type CliIdentity, DEFAULT_MANIFEST_CHECKS, DOCTOR_CHECKS_TOKEN, DiscoveryCommands, DiscoveryScanCommand, DiscoverySnapshotDoctorCheck, type DoctorCheck, type DoctorCheckResult, DoctorCommands, DoctorFlow, type DoctorReport, MANIFEST_ACCESS_PORT_TOKEN, MANIFEST_CHECKS_TOKEN, type ManifestCheck, ManifestCheckCommand, type ManifestCheckReport, type ManifestCheckResult, ManifestCliFlow, ManifestCommands, type ManifestDiff, ManifestDumpCommand, ManifestHashCommand, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, PLATFORM_DOCTOR_CHECK_PROVIDERS, PlanCatalogDoctorCheck, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WhoAmIFlow, type WhoAmIResult, applyFragmentBlocks, extractModelBlocks, extractModelNames };