primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

package/dist/src/lib/snapshots.js

@@ -0,0 +1,357 @@
+/**
+ * Sync snapshots — point-in-time backups of a sync directory taken before a
+ * destructive `config pull` overwrites local TOML state (issue #578, Phase 1).
+ *
+ * A snapshot is a full recursive copy of the live sync tree (including
+ * `.primitive-sync.json`, the content-hash baseline) into a timestamped slot
+ * under the snapshots root:
+ *
+ *   <snapshotsRoot>/<YYYY-MM-DDTHH-MM-SS>/
+ *       <full pre-pull copy of the sync tree, incl. .primitive-sync.json>
+ *       .snapshot-complete        # integrity marker, written LAST
+ *       .audit-id                 # ULID cross-link (Phase 2; absent in P1)
+ *
+ * The `.snapshot-complete` marker is written last so a partial/interrupted
+ * copy is detectable: `restoreSnapshot` refuses any snapshot missing it.
+ *
+ * Snapshots fail LOUD — `createSnapshot` throws if it can't write a complete
+ * snapshot. The caller (config pull) aborts before touching any local file so we
+ * never perform a destructive pull without a recoverable backup.
+ *
+ * Restore is staged-then-swapped: the snapshot is materialized into a sibling
+ * temp dir, then the live `configDir` is atomically replaced, so a mid-restore
+ * crash never leaves a half-written tree.
+ */
+import { existsSync, readdirSync, statSync, writeFileSync, readFileSync, cpSync, rmSync, renameSync, mkdirSync, mkdtempSync, } from "fs";
+import { join, dirname, resolve, relative, isAbsolute } from "path";
+/**
+ * Returns true if `child` is `parent` or lives somewhere beneath it. Used to
+ * detect the legacy `--dir` case where the snapshots root sits INSIDE the sync
+ * tree (`<userDir>/.snapshots/`) — we must not copy that subtree into the
+ * snapshot, or `cpSync` recurses into itself.
+ */
+function isInside(parent, child) {
+    const rel = relative(resolve(parent), resolve(child));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/** Marker file written LAST inside a snapshot to prove it completed. */
+export const SNAPSHOT_COMPLETE_MARKER = ".snapshot-complete";
+/** Cross-link to the audit entry that produced the snapshot (Phase 2). */
+export const SNAPSHOT_AUDIT_ID_MARKER = ".audit-id";
+/**
+ * Produce the timestamp directory name for a snapshot, e.g.
+ * `2026-06-01T17-42-18`. Colons (illegal on Windows, awkward everywhere) are
+ * replaced with hyphens; milliseconds and the trailing `Z` are dropped.
+ */
+function snapshotTimestamp(now = new Date()) {
+    // 2026-06-01T17:42:18.401Z -> 2026-06-01T17-42-18
+    return now.toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
+}
+/**
+ * Returns true if `dir` exists and contains at least one entry. A fresh
+ * project (no prior sync dir, or an empty one) has nothing to back up.
+ */
+function dirHasContent(dir) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Snapshot the current `syncDir` into a new timestamped slot under
+ * `snapshotsRoot`. Returns the created snapshot, or `null` when there's
+ * nothing to back up (missing/empty `syncDir`).
+ *
+ * Fails LOUD: throws if the copy or marker write fails. The partial snapshot
+ * dir is best-effort cleaned up before rethrowing so a failed snapshot never
+ * leaves a marker-less husk behind.
+ */
+export function createSnapshot(syncDir, snapshotsRoot, opts = {}) {
+    if (!dirHasContent(syncDir)) {
+        return null;
+    }
+    const id = snapshotTimestamp(opts.now);
+    const dest = join(snapshotsRoot, id);
+    // Guard against an id collision (two pulls within the same second). Append a
+    // numeric suffix until we find a free slot so a rapid second pull can't
+    // clobber the first snapshot.
+    let finalId = id;
+    let finalDest = dest;
+    let suffix = 1;
+    while (existsSync(finalDest)) {
+        finalId = `${id}-${suffix}`;
+        finalDest = join(snapshotsRoot, finalId);
+        suffix += 1;
+    }
+    // Fork 4: under legacy `--dir`, the snapshots root lives INSIDE the sync
+    // tree (`<userDir>/.snapshots/`). Node's cpSync refuses to copy a directory
+    // into its own subtree (ERR_FS_CP_EINVAL) even with a filter, so in that
+    // case we stage the copy into an external temp dir (excluding the backups
+    // subtree) and then move it into place.
+    const rootIsInside = isInside(syncDir, snapshotsRoot);
+    const snapshotsRootResolved = resolve(snapshotsRoot);
+    const filter = rootIsInside
+        ? (src) => !isInside(snapshotsRootResolved, src)
+        : undefined;
+    let externalStage = null;
+    try {
+        mkdirSync(snapshotsRoot, { recursive: true });
+        if (rootIsInside) {
+            // Copy to a sibling of syncDir first (outside the sync tree, so no
+            // self-recursion), then move into the inside-the-tree slot. Staging in
+            // the parent keeps the move same-filesystem (avoids cross-device EXDEV
+            // that a tmpdir stage could hit).
+            const parent = dirname(resolve(syncDir));
+            mkdirSync(parent, { recursive: true });
+            externalStage = mkdtempSync(join(parent, ".primitive-snapshot-stage-"));
+            const stageTree = join(externalStage, "tree");
+            cpSync(syncDir, stageTree, {
+                recursive: true,
+                dereference: false,
+                ...(filter ? { filter } : {}),
+            });
+            renameSync(stageTree, finalDest);
+        }
+        else {
+            // Full recursive copy. `dereference: false` keeps symlinks from being
+            // silently followed (edge case: symlinks inside the sync tree).
+            cpSync(syncDir, finalDest, { recursive: true, dereference: false });
+        }
+        if (opts.auditId) {
+            writeFileSync(join(finalDest, SNAPSHOT_AUDIT_ID_MARKER), opts.auditId);
+        }
+        // Integrity marker written LAST — its presence proves the copy finished.
+        writeFileSync(join(finalDest, SNAPSHOT_COMPLETE_MARKER), new Date().toISOString());
+    }
+    catch (err) {
+        // Best-effort cleanup of the partial snapshot so we don't leave an
+        // incomplete (marker-less) directory around.
+        try {
+            rmSync(finalDest, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup failure
+        }
+        throw err;
+    }
+    finally {
+        if (externalStage) {
+            try {
+                rmSync(externalStage, { recursive: true, force: true });
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return { id: finalId, path: finalDest };
+}
+/**
+ * List snapshots under `snapshotsRoot`, newest-first. Returns an empty array
+ * if the root doesn't exist. Each entry reports whether it's complete and any
+ * cross-linked audit id.
+ */
+export function listSnapshots(snapshotsRoot) {
+    if (!existsSync(snapshotsRoot))
+        return [];
+    let names;
+    try {
+        names = readdirSync(snapshotsRoot);
+    }
+    catch {
+        return [];
+    }
+    const infos = [];
+    for (const name of names) {
+        const path = join(snapshotsRoot, name);
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        const complete = existsSync(join(path, SNAPSHOT_COMPLETE_MARKER));
+        let auditId = null;
+        const auditPath = join(path, SNAPSHOT_AUDIT_ID_MARKER);
+        if (existsSync(auditPath)) {
+            try {
+                auditId = readFileSync(auditPath, "utf-8").trim() || null;
+            }
+            catch {
+                auditId = null;
+            }
+        }
+        infos.push({ id: name, path, complete, auditId, createdAt: stat.mtime });
+    }
+    // Newest first. The id is a sortable timestamp string, so a reverse string
+    // sort matches chronological order (and stays correct for the `-N` suffixed
+    // collision variants within the same second).
+    infos.sort((a, b) => (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+    return infos;
+}
+/**
+ * Resolve a snapshot by id within `snapshotsRoot`. Accepts either the full
+ * timestamp directory name OR a unique prefix of at least `minPrefix`
+ * characters (default 8). Returns the matching snapshot, or throws a clear
+ * error on no-match / ambiguous-prefix.
+ *
+ * When `id` is omitted, resolves to the most recent COMPLETE snapshot.
+ */
+export function resolveSnapshot(snapshotsRoot, id, minPrefix = 8) {
+    const all = listSnapshots(snapshotsRoot);
+    if (all.length === 0) {
+        throw new Error(`No snapshots found in ${snapshotsRoot}`);
+    }
+    if (!id) {
+        const mostRecentComplete = all.find((s) => s.complete);
+        if (!mostRecentComplete) {
+            throw new Error(`No complete snapshots found in ${snapshotsRoot} (all are missing the ${SNAPSHOT_COMPLETE_MARKER} marker).`);
+        }
+        return mostRecentComplete;
+    }
+    // Exact match wins.
+    const exact = all.find((s) => s.id === id);
+    if (exact)
+        return exact;
+    // Prefix match (must be unique and >= minPrefix chars).
+    if (id.length < minPrefix) {
+        throw new Error(`Snapshot id "${id}" is too short — provide at least ${minPrefix} characters or the full timestamp.`);
+    }
+    const matches = all.filter((s) => s.id.startsWith(id));
+    if (matches.length === 0) {
+        throw new Error(`No snapshot matches "${id}" in ${snapshotsRoot}`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Snapshot prefix "${id}" is ambiguous (${matches.length} matches: ${matches
+            .map((m) => m.id)
+            .join(", ")}). Provide more characters.`);
+    }
+    return matches[0];
+}
+/**
+ * Restore a snapshot into `syncDir`, replacing whatever is there.
+ *
+ * Refuses to restore a snapshot missing the `.snapshot-complete` marker
+ * (partial/corrupted snapshot). The internal marker files (`.snapshot-complete`,
+ * `.audit-id`) are NOT copied into the restored tree.
+ *
+ * Staged-then-swapped: the snapshot is materialized into a sibling temp dir,
+ * then `syncDir` is atomically replaced, so a mid-restore crash never leaves a
+ * half-written tree.
+ *
+ * `opts.preserveDir` names a directory (the snapshots root) that lives INSIDE
+ * `syncDir` and must survive the full-tree swap — the Fork-4 legacy `--dir`
+ * case, where backups sit at `<syncDir>/.snapshots/`. Without preserving it,
+ * the swap would wipe the user's entire snapshot history on restore.
+ */
+export function restoreSnapshot(snapshotPath, syncDir, opts = {}) {
+    if (!existsSync(snapshotPath)) {
+        throw new Error(`Snapshot not found: ${snapshotPath}`);
+    }
+    if (!existsSync(join(snapshotPath, SNAPSHOT_COMPLETE_MARKER))) {
+        throw new Error(`Refusing to restore: snapshot ${snapshotPath} is missing the ${SNAPSHOT_COMPLETE_MARKER} marker (partial/corrupted snapshot).`);
+    }
+    const parent = dirname(syncDir);
+    mkdirSync(parent, { recursive: true });
+    const unique = `${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+    const stageDir = join(parent, `.primitive-restore-stage-${unique}`);
+    const oldDir = join(parent, `.primitive-restore-old-${unique}`);
+    // Determine whether a backups dir living inside syncDir needs preserving.
+    const preserve = opts.preserveDir &&
+        isInside(syncDir, opts.preserveDir) &&
+        !isInside(snapshotPath, opts.preserveDir) // don't preserve a dir that's part of the snapshot
+        ? resolve(opts.preserveDir)
+        : null;
+    const preserveStash = preserve
+        ? join(parent, `.primitive-restore-keep-${unique}`)
+        : null;
+    try {
+        // Materialize the snapshot into the staging dir.
+        cpSync(snapshotPath, stageDir, { recursive: true, dereference: false });
+        // Drop the snapshot-internal marker files from the restored tree.
+        for (const marker of [SNAPSHOT_COMPLETE_MARKER, SNAPSHOT_AUDIT_ID_MARKER]) {
+            const markerPath = join(stageDir, marker);
+            if (existsSync(markerPath)) {
+                rmSync(markerPath, { force: true });
+            }
+        }
+        // Atomic-ish swap: move the live dir aside, move staging into place, then
+        // delete the old dir. Same-filesystem renames are atomic.
+        if (existsSync(syncDir)) {
+            renameSync(syncDir, oldDir);
+        }
+        try {
+            renameSync(stageDir, syncDir);
+        }
+        catch (err) {
+            // Swap failed — try to roll the original back so we never leave the
+            // user with no sync dir at all.
+            if (existsSync(oldDir) && !existsSync(syncDir)) {
+                try {
+                    renameSync(oldDir, syncDir);
+                }
+                catch {
+                    // ignore rollback failure; original error is more useful
+                }
+            }
+            throw err;
+        }
+        // Re-attach the preserved backups dir (Fork-4 `--dir` mode) into the
+        // freshly-restored tree, pulling it out of the displaced original.
+        if (preserve && preserveStash) {
+            const rel = relative(resolve(syncDir), preserve);
+            const fromOld = join(oldDir, rel);
+            const intoNew = join(syncDir, rel);
+            if (existsSync(fromOld) && !existsSync(intoNew)) {
+                mkdirSync(dirname(intoNew), { recursive: true });
+                renameSync(fromOld, intoNew);
+            }
+        }
+        // Success — remove the displaced original.
+        if (existsSync(oldDir)) {
+            rmSync(oldDir, { recursive: true, force: true });
+        }
+    }
+    finally {
+        // Clean up any leftover staging/old/stash dirs on failure.
+        for (const dir of [stageDir, oldDir, preserveStash].filter((d) => Boolean(d))) {
+            if (existsSync(dir)) {
+                try {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+}
+/**
+ * Prune snapshots older than `retentionDays` from `snapshotsRoot`. Only the
+ * given slot is touched (cross-slot retention is independent — each slot has
+ * its own snapshots root). No-op if the root doesn't exist.
+ */
+export function pruneSnapshots(snapshotsRoot, retentionDays = 28) {
+    if (!existsSync(snapshotsRoot))
+        return;
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    for (const info of listSnapshots(snapshotsRoot)) {
+        if (info.createdAt.getTime() < cutoff) {
+            try {
+                rmSync(info.path, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort prune — a failure to delete one stale snapshot must not
+                // abort the pull that triggered the prune.
+            }
+        }
+    }
+}
+//# sourceMappingURL=snapshots.js.map

package/dist/src/lib/snapshots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshots.js","sourceRoot":"","sources":["../../../src/lib/snapshots.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/swift-codegen/dbGenerator.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `databases codegen --lang swift` orchestrator (issue #1547, Phase 4).
+ *
+ * The Swift counterpart of `db-codegen/dbGenerator.ts`. Reads the SAME synced
+ * `database-type-configs/*.toml` and emits ONE `<type>.generated.swift` per database
+ * type. Each file carries the type's record structs (read shape), per-op params
+ * structs (write shape), per-op result typealiases, and a typed `<Type>Ops`
+ * factory over the additive generic `executeOperation` overload on
+ * `DatabasesAPI` (the only published SDK surface for this generator).
+ *
+ * Design decisions realized (issue #1547):
+ *   - Operation + record metadata (which ops exist, their params, their result
+ *     descriptor, and per-model fields) is read from the SHARED `describeDbType`
+ *     IR — the SAME source the TS renderer (`db-codegen/dbGenerator.ts`) reads.
+ *     The Swift renderer reconstructs none of it (binding item 5), so the two
+ *     clients can never disagree on a type's surface.
+ *   - The generic result envelopes (`DBQueryResult<T>`, `DBMutationResult`, …)
+ *     live in the JsBaoClient SDK, NOT emitted per file — a Swift package
+ *     compiles all generated files into one module, so a per-file copy would
+ *     collide. Generated files reference the SDK envelopes (mirrors how Phase 3
+ *     put the workflow result envelopes in the SDK).
+ *   - Swift has no analog of TS `Pick<M, …>` / `Partial<M>`, so a query op with
+ *     a `pick`/`partial` projection types its rows as the open `JSONValue`
+ *     rather than a narrowed record (the same Fork-4 "no clean analog →
+ *     JSONValue" fallback the emitter uses for un-descended schema nodes). A
+ *     `full` projection over a known record types as `DBQueryResult<Record>`.
+ *   - Disk lifecycle (write / `--check` / orphan cleanup) delegates to the
+ *     shared `writeOrCheckGeneratedFiles`, scoped by an ownership BANNER
+ *     distinct from both the workflow Swift banner and the model codegen's, so
+ *     a shared Swift output dir stays safe.
+ */
+import { type WriteOrCheckResult } from "../codegen-shared/generatedFiles.js";
+import { type DbCodegenInput } from "../db-codegen/dbTypeIR.js";
+/**
+ * Banner prefix stamped on every CLI-emitted database `.generated.swift` file.
+ * Distinct from both the workflow Swift banner (`// AUTO-GENERATED FROM
+ * workflows/`) and the model codegen's (`// Generated by swift-bao-codegen`),
+ * so none of the three generators' stale-sweeps ever deletes another's files
+ * when they share an output dir.
+ */
+export declare const DB_SWIFT_BANNER_PREFIX = "// AUTO-GENERATED FROM database-type-configs/";
+/**
+ * The banner this generator stamped before issue #2760 renamed the source
+ * directory. RECOGNITION ONLY — nothing emits it.
+ *
+ * Ownership everywhere is `contents.startsWith(banner)`, so without this a file
+ * generated before the rename would match neither the db banner nor the
+ * workflow one: it would survive the db stale sweep as a stranger, stay
+ * invisible to the sibling-symbol scans, and be silently overwritten by
+ * `workflows codegen --lang swift` on a name collision instead of refused.
+ */
+export declare const LEGACY_DB_SWIFT_BANNER_PREFIX = "// AUTO-GENERATED FROM database-types/";
+/** Both spellings, for every ownership check this generator performs. */
+export declare const DB_SWIFT_BANNER_PREFIXES: string[];
+export interface GenerateDbSwiftTypesOptions {
+    inputs: DbCodegenInput[];
+    /** Directory where the `<type>.generated.swift` files are written. */
+    outputDir: string;
+    /** `--check`: compare against disk, do not write. */
+    check?: boolean;
+    /**
+     * Set when the run was filtered to a single database type. `inputs` is then a
+     * PARTIAL view, so orphan cleanup / stale detection is scoped to the filtered
+     * file. Mirrors the TS generator's `singleType`.
+     */
+    singleType?: boolean;
+}
+/** Swift record struct type name for a model (shared naming + Swift sanitize). */
+export declare function dbRecordSwiftTypeName(modelName: string, className: string | undefined): string;
+/**
+ * Namespace `enum` name for a database type (issue #1687). Every symbol a type
+ * emits is nested under `public enum <Type>` (`securities-ref` →
+ * `SecuritiesRef`), so two DB types can never collide on a shared op symbol.
+ * Reuses the same `structTypeName` sanitizer (keyword suffixing + digit-leading
+ * `_` guard) the old `<Type>Ops` derivation used, so the namespace name is a
+ * legal Swift type identifier.
+ */
+export declare function dbNamespaceName(databaseType: string): string;
+/**
+ * Validate that a database type's derived namespace enum name is safe to emit,
+ * and return it. Throws a named `SwiftCodegenError` (with a rename hint) for
+ * the whole class of unsafe names a server-accepted database type can produce
+ * (#1687):
+ *
+ *   1. **Degenerate `_`** — a type with no retained identifier characters
+ *      (empty after sanitize, or separator/emoji/punctuation-only, e.g. `--`,
+ *      `🎉`) normalizes to `_` via `structTypeName`. Swift reserves `_` as the
+ *      wildcard and rejects `public enum _` (Codex [P2]).
+ *   2. **Stdlib/SDK shadowing** — a name in `RESERVED_NAMESPACE_NAMES` shadows
+ *      a type the generated body references unqualified (Codex [P1]).
+ *
+ * Leading-digit residue (`123` → `_123`) and Swift reserved words (`self` →
+ * `Self_`, `any` → `Any_`) are already lifted into legal, non-shadowing
+ * identifiers by `structTypeName` (digit-leading `_` guard + keyword suffix),
+ * so they need no rejection here — only names that survive that sanitizer as
+ * `_` or as a real type identifier remain unsafe. The two in-run / retained-
+ * sibling namespace-NAME collision guards (two database types whose names
+ * normalize to the SAME enum) live in `generateDbSwiftTypes`; this check
+ * covers the single-type unsafe-name class.
+ */
+export declare function assertSafeNamespaceName(databaseType: string, sourceFile: string): string;
+/**
+ * Render the full `<type>.generated.swift` content for one database-type TOML.
+ * Pure — exported so tests can assert on the string directly. Throws on a Swift
+ * record type-name collision between two models (mirrors the TS collision guard).
+ */
+export declare function renderDbTypeSwiftFile(input: DbCodegenInput): string;
+/**
+ * Run Swift database codegen end-to-end. One `<type>.generated.swift` per
+ * database type; delegates the disk lifecycle to the shared writer/checker with
+ * banner-scoped ownership so a shared Swift output dir stays safe.
+ */
+export declare function generateDbSwiftTypes(options: GenerateDbSwiftTypesOptions): Promise<WriteOrCheckResult>;