create-noy-db 0.9.0 → 0.10.0-pre.1

package/dist/index.d.ts

@@ -50,6 +50,7 @@ interface WizardMessages {
     adapterMemoryLabel: string;
     /** "Include sample invoice records?" confirm label. */
     promptSampleData: string;
+    promptRecommended: string;
     /** Title of the "Next steps" note block. */
     freshNextStepsTitle: string;
     /** Success banner shown after the fresh project is created. */
@@ -111,15 +112,18 @@ type WizardAdapter = 'browser' | 'file' | 'memory';
 /**
  * Which starter template to scaffold in fresh-project mode.
  *
- * - `nuxt-default` — Nuxt 4 + Pinia + in-nuxt, SSR-friendly. Default.
- * - `vanilla` — Vite + TS, no framework. Smallest footprint.
+ * - `minimal` — Vite + TS, one file: open a vault, put/get. **Default** since 2026-10-11
+ *   (family#115): the recommended door scaffolded Nuxt (628 packages) while the
+ *   README promised "nothing beyond hub".
+ * - `nuxt-default` — Nuxt 4 + Pinia + in-nuxt, SSR-friendly.
+ * - `vanilla` — Vite + TS, no framework, an invoice table UI.
  * - `vite-vue` — Vite + Vue 3 + Pinia + in-pinia. Client-side SPA.
  * - `electron` — Electron + Vue 3 + to-file. USB-stick / local-disk workflow.
  *
  * Augment mode (detected Nuxt project) ignores this field — the
  * mutation path is shared regardless of the original scaffold.
  */
-type WizardTemplate = 'nuxt-default' | 'vanilla' | 'vite-vue' | 'electron';
+type WizardTemplate = 'minimal' | 'nuxt-default' | 'vanilla' | 'vite-vue' | 'electron';
 /**
  * Inputs to `runWizard()`. All fields are optional — when a field is
  * omitted the wizard prompts for it. Tests pass everything to skip
@@ -694,4 +698,274 @@ interface BackupResult {
 declare function resolveBackupTarget(target: string, cwd?: string): string;
 declare function backup(options: BackupOptions): Promise<BackupResult>;
 
-export { type AddCollectionOptions, type AddUserOptions, type AddUserResult, type BackupOptions, type BackupResult, type Locale, type ReadSecret, type RotateOptions, type RotateResult, SUPPORTED_LOCALES, type VerifyResult, type WizardMessages, type WizardOptions, type WizardResult, addCollection, addUser, assertRole, backup, detectLocale, loadMessages, parseCollectionList, parseLocaleFlag, resolveBackupTarget, rotate, runWizard, verifyIntegrity };
+interface InspectResult {
+    formatVersion: number;
+    handle: string;
+    bodyBytes: number;
+    bodySha256: string;
+}
+declare function inspect(filePath: string): Promise<InspectResult>;
+declare function runInspect(argv: readonly string[]): Promise<number>;
+
+interface VerifyReport {
+    ok: boolean;
+    file: string;
+    handle: string;
+    bodyBytes: number;
+    checks: {
+        magic: boolean;
+        header: boolean;
+        bodyHash: boolean;
+    };
+    error?: string;
+}
+declare function verify(filePath: string): Promise<VerifyReport>;
+declare function runVerify(argv: readonly string[]): Promise<number>;
+
+interface ValidationIssue {
+    severity: 'warn' | 'error';
+    code: string;
+    path: string;
+    message: string;
+}
+interface ValidationReport {
+    ok: boolean;
+    issues: ValidationIssue[];
+}
+declare function validateOptions(opts: unknown): ValidationReport;
+/** Dynamically import a JS/MJS/CJS config file and pull the NoydbOptions
+ *  out of it. Accepts a default export that is either the options
+ *  object or a zero-arg function (sync or async) returning the options.
+ *
+ *  **TypeScript note.** Node cannot `import()` a bare `.ts` file without
+ *  a loader. If the adopter's config is TypeScript, they should either
+ *  compile it first (`tsc foo.ts`) or run the CLI under a TS-capable
+ *  runtime (e.g. `tsx $(which noy-db) config validate foo.ts`). The
+ *  function throws a human-readable error for `.ts` input rather than
+ *  propagating Node's cryptic `Unknown file extension` message. */
+declare function loadOptionsFromFile(filePath: string): Promise<unknown>;
+declare function runConfigValidate(argv: readonly string[]): Promise<number>;
+/**
+ * The ten topology profiles. ⛔ This table IS the documentation: until 2026-10-11
+ * every pointer went to `docs/guides/topology-matrix.md`, a path that existed in
+ * no public repo, so profiles B–J were undiscoverable from the CLI (family#109).
+ * `noy-db config profiles` prints it; a profile's `notes` string stays the one
+ * authority for what it is.
+ */
+declare const PROFILE_IDS: readonly ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J"];
+type Profile = (typeof PROFILE_IDS)[number];
+interface ScaffoldResult {
+    profile: Profile;
+    code: string;
+    env: string;
+    notes: string;
+}
+declare function scaffold(profile: Profile): ScaffoldResult;
+/** One line per profile — the `notes` string of each, which is the authority. */
+declare function listProfiles(): string;
+declare function runConfigProfiles(): number;
+declare function runConfigScaffold(argv: readonly string[]): Promise<number>;
+
+/**
+ * One method's timings. Names only the fields this formatter READS; the index
+ * signature carries the rest a real snapshot reports (`p90` today).
+ *
+ * ⭐ Open on purpose. Mirroring to-meter's exact field list would make this a
+ * structural twin that drifts the moment to-meter adds a percentile — and
+ * drift is the cost the local declaration exists to avoid, not one to
+ * re-import.
+ */
+interface MeterMethodStats {
+    readonly count: number;
+    readonly errors: number;
+    readonly p50: number;
+    readonly p99: number;
+    readonly max: number;
+    readonly avg: number;
+    readonly [stat: string]: number;
+}
+/**
+ * The six core store methods are always present. A real snapshot carries more
+ * — `p90`, plus the optional half of the store contract (`listPage`, `tx`, …)
+ * — and the index signature is what lets it satisfy this view; the NAMED
+ * members are what keep `byMethod[m]` safe under `noUncheckedIndexedAccess`.
+ *
+ * ⚠️ That a real snapshot populates EVERY key is to-meter's invariant, not
+ * ours, and it is witnessed there (`__tests__/meter-composition.test.ts`).
+ * This view deliberately cannot assert it.
+ */
+interface MeterByMethod {
+    readonly get: MeterMethodStats;
+    readonly put: MeterMethodStats;
+    readonly delete: MeterMethodStats;
+    readonly list: MeterMethodStats;
+    readonly loadAll: MeterMethodStats;
+    readonly saveAll: MeterMethodStats;
+    readonly [method: string]: MeterMethodStats;
+}
+/** The slice of to-meter's `MeterSnapshot` this formatter reads. */
+interface MeterSnapshotView {
+    readonly collectedAt: string;
+    readonly status: string;
+    readonly totalCalls: number;
+    readonly casConflicts: number;
+    readonly windowMs: number;
+    readonly byMethod: MeterByMethod;
+}
+interface MonitorOptions {
+    intervalMs: number;
+    iterations?: number;
+}
+declare function runMonitor(argv: readonly string[]): Promise<number>;
+declare function formatSnapshot(snap: MeterSnapshotView): string;
+
+/**
+ * `noy-db describe <file.noydb>` — emit a human-readable YAML/JSON
+ * description of a bundle's structure (collections, fields, indexes,
+ * FKs, MVs, overlays, derivations) with optional counters.
+ *
+ * Loads the bundle into an in-memory store, unlocks it with the
+ * supplied secret + user, calls `vault.dumpSchema()`, then emits.
+ *
+ * See `design-history/2026-05-22-schema-dump-design.md`.
+ *
+ * @module
+ */
+type DescribeFormat = 'yaml' | 'json';
+type SchemasMode = 'none' | 'full' | 'sidecar';
+interface DescribeOptions {
+    readonly bundlePath: string;
+    readonly user: string;
+    readonly secret: string;
+    readonly format: DescribeFormat;
+    readonly withStats: boolean;
+    readonly schemas: SchemasMode;
+    readonly outPath?: string;
+    readonly sampleSize: number;
+}
+/** Run the full describe pipeline and return the emitted string. */
+declare function describeBundle(opts: DescribeOptions): Promise<string>;
+declare function runDescribe(argv: readonly string[]): Promise<number>;
+
+type DoctorLevel = 'error' | 'warn' | 'info';
+type DoctorMode = 'dev' | 'prod';
+interface DoctorFinding {
+    /** Stable, e.g. `NOY-R001`. */
+    readonly id: string;
+    readonly level: DoctorLevel;
+    /** One line: what is wrong. */
+    readonly message: string;
+    /** One line: what to do. Always present — a finding without a fix is a complaint. */
+    readonly fix: string;
+    /** Where it was seen: a config path, a file, a vault. */
+    readonly where?: string;
+}
+/** The input a check sees. Nothing here requires a secret. */
+interface DoctorContext {
+    readonly mode: DoctorMode;
+    /** The project directory (where package.json lives). */
+    readonly root: string;
+    /** The config file, when one was found/given. */
+    readonly configPath?: string;
+    /** The loaded options object, untyped on purpose — a check narrows what it reads. */
+    readonly options?: Record<string, unknown>;
+    /** The store from the config, when it has one. */
+    readonly store?: NoydbStore;
+    /** Vault names to inspect. From `--vault`, else the ones the store lists, else none. */
+    readonly vaults: readonly string[];
+    /** package.json of the project, parsed. */
+    readonly manifest: {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+    };
+}
+interface DoctorCheck {
+    readonly id: string;
+    readonly run: (ctx: DoctorContext) => Promise<readonly DoctorFinding[]> | readonly DoctorFinding[];
+}
+interface DoctorReport {
+    readonly mode: DoctorMode;
+    readonly findings: readonly DoctorFinding[];
+    readonly counts: Record<DoctorLevel, number>;
+    /** Which check ids ran, so a `--json` consumer can tell "clean" from "not covered". */
+    readonly ran: readonly string[];
+}
+declare const BUILTIN_CHECKS: readonly DoctorCheck[];
+interface DoctorOptions {
+    readonly root?: string;
+    readonly configPath?: string;
+    readonly mode?: DoctorMode;
+    readonly vaults?: readonly string[];
+    /** Skip importing satellites (tests, or an untrusted node_modules). */
+    readonly noSatellites?: boolean;
+}
+declare function doctor(opts?: DoctorOptions): Promise<DoctorReport>;
+/** The idempotent fixes. Returns what it changed. Only NOY-H001 today. */
+declare function applyFixes(root: string, report: DoctorReport): string[];
+declare function formatReport(r: DoctorReport): string;
+declare function runDoctor(argv: readonly string[]): Promise<number>;
+
+declare const CATALOG_URL = "https://noy-db.lanna.ai/catalog.json";
+interface CatalogPrefix {
+    readonly reads: string;
+    readonly layer: string;
+    readonly plaintext: string;
+    readonly trust: string;
+}
+interface CatalogPackage {
+    readonly id: string;
+    readonly name: string;
+    readonly package: string;
+    readonly prefix: string;
+    readonly section: string;
+    readonly status: string;
+    readonly producer: string | null;
+    readonly useCase?: string;
+}
+interface Catalog {
+    readonly schemaVersion: number;
+    readonly prefixes: Record<string, CatalogPrefix>;
+    readonly packages: readonly CatalogPackage[];
+}
+/** The shipped snapshot — always available. */
+declare function bundledCatalog(): Catalog;
+/** Live first, snapshot second. Says which one it used. */
+declare function loadCatalog(opts?: {
+    offline?: boolean;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    catalog: Catalog;
+    source: 'live' | 'bundled';
+}>;
+/** `to-`, `to`, `@noy-db/to-` and `storage`-style words all mean the to- prefix. */
+declare function normalisePrefix(input: string | undefined): string | undefined;
+declare function formatList(catalog: Catalog, prefix?: string): string;
+/** Resolve a user's spelling to a catalog row: `to-aws-s3`, `aws-s3`, `@noy-db/to-aws-s3`. */
+declare function findPackage(catalog: Catalog, input: string): CatalogPackage | undefined;
+type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
+/** Detect from the lockfile present in `root`; pnpm when nothing says otherwise. */
+declare function detectPackageManager(root: string): PackageManager;
+/** The install command, as argv. `yarn add` and `bun add` differ from `npm install`. */
+declare function installArgv(pm: PackageManager, pkg: string, dev: boolean): string[];
+/** What to paste after installing, by layer. Short on purpose: the README of the package is the manual. */
+declare function snippetFor(p: CatalogPackage): string;
+interface AddOptions {
+    readonly root?: string;
+    readonly dev?: boolean;
+    readonly dryRun?: boolean;
+    readonly offline?: boolean;
+    readonly fetchImpl?: typeof fetch;
+}
+interface AddResult {
+    readonly pkg: CatalogPackage;
+    readonly installed: boolean;
+    readonly command: string[];
+    readonly wired: 'nuxt-module' | null;
+    readonly trust: string;
+    readonly snippet: string;
+}
+declare function addPackage(input: string, opts?: AddOptions): Promise<AddResult>;
+declare function runAddPackage(argv: readonly string[]): Promise<number>;
+
+export { type AddCollectionOptions, type AddOptions, type AddResult, type AddUserOptions, type AddUserResult, BUILTIN_CHECKS, type BackupOptions, type BackupResult, CATALOG_URL, type Catalog, type CatalogPackage, type CatalogPrefix, type DescribeFormat, type DescribeOptions, type DoctorCheck, type DoctorContext, type DoctorFinding, type DoctorLevel, type DoctorMode, type DoctorOptions, type DoctorReport, type InspectResult, type Locale, type MeterSnapshotView, type MonitorOptions, PROFILE_IDS, type PackageManager, type Profile, type ReadSecret, type RotateOptions, type RotateResult, SUPPORTED_LOCALES, type ScaffoldResult, type SchemasMode, type ValidationIssue, type ValidationReport, type VerifyReport, type VerifyResult, type WizardMessages, type WizardOptions, type WizardResult, addCollection, addPackage, addUser, applyFixes, assertRole, backup, bundledCatalog, describeBundle, detectLocale, detectPackageManager, doctor, findPackage, formatList, formatReport, formatSnapshot, inspect, installArgv, listProfiles, loadCatalog, loadMessages, loadOptionsFromFile, normalisePrefix, parseCollectionList, parseLocaleFlag, resolveBackupTarget, rotate, runAddPackage, runConfigProfiles, runConfigScaffold, runConfigValidate, runDescribe, runDoctor, runInspect, runMonitor, runVerify, runWizard, scaffold, snippetFor, validateOptions, verify, verifyIntegrity };