feat: add auth user bootstrap helper

[Jess Sullivan (Jesssullivan)]

Summary

• Add bootstrapUsers() as a tenant-scoped auth user bootstrap helper for deploy/startup flows.
• Support injected storage, caller-owned pg.Pool, or a connection string while keeping create/update behavior on the shared adapter boundary.
• Export the helper from the package root and ./bootstrap-users, bump package/Bazel metadata to 0.2.4, and document the API.

Validation

• pnpm install --frozen-lockfile
• pnpm typecheck
• pnpm build
• pnpm test -- bootstrap-users
• pnpm check:package
• bazel build //:pkg
• git diff --check

[greptile-apps]

Greptile Summary

This PR introduces bootstrapUsers(), a tenant-scoped idempotent helper for seeding admin users during deploy/startup, supporting injected storage, caller-owned pg.Pool, or a connection string. Both prior P1s from the previous review (unconditional lifecycle-field overwrite and unnecessary password hashing on updateExisting: false) are correctly addressed: toUpdateUser is now narrowly scoped and hashing is deferred past the early-exit guard.

Confidence Score: 5/5

Safe to merge — both prior P1s are resolved and no new blocking issues were found.

All findings are P2 (error masking in finally, missing duplicate-handle guard). The core correctness concerns from the previous review round have been fully addressed with tests covering each behavior.

No files require special attention.

Important Files Changed

Filename	Overview
src/bootstrap-users.ts	New bootstrap helper with well-structured discriminated-union config, correct lifecycle-preserving update logic, and deferred password hashing; minor P2s around error masking in finally and missing duplicate-handle guard.
src/tests/bootstrap-users.test.ts	Comprehensive unit tests covering cold-start creation, idempotency, lifecycle-field preservation, updateExisting: false, and missing-credential errors; all previously flagged behaviors are now tested.
src/index.ts	Clean re-export of bootstrapUsers and all related public types from the new module.
package.json	Version bumped to 0.2.4 and new ./bootstrap-users conditional export added with correct types/import entries.
BUILD.bazel	Version bumped to 0.2.4 to match package.json.
CHANGELOG.md	0.2.4 entry correctly documents the new bootstrapUsers export and the adapter-boundary rationale.
README.md	New bootstrap section and API reference block added; the password credential field is still omitted from the type snippet (noted in a previous review thread).

Sequence Diagram

sequenceDiagram
    participant Caller
    participant bootstrapUsers
    participant resolveStorage
    participant normalizeBootstrapUser
    participant storage as BootstrapUserStorage

    Caller->>bootstrapUsers: config (tenantId, users, pool/storage/connectionString)
    bootstrapUsers->>resolveStorage: config
    resolveStorage-->>bootstrapUsers: { storage, close? }

    loop for each user
        bootstrapUsers->>normalizeBootstrapUser: rawUser, index
        normalizeBootstrapUser-->>bootstrapUsers: normalized user (throws on bad input)
        bootstrapUsers->>storage: getUserByHandle(tenantId, handle)
        storage-->>bootstrapUsers: existing | null

        alt existing && !updateExisting
            bootstrapUsers-->>bootstrapUsers: push unchanged, continue
        else no existing
            bootstrapUsers->>bootstrapUsers: resolvePasswordHash(user, hasher)
            bootstrapUsers->>storage: createUser(tenantId, toCreateUser(...))
            storage-->>bootstrapUsers: created TenantScoped AdminUser
            bootstrapUsers-->>bootstrapUsers: push created
        else existing && updateExisting
            bootstrapUsers->>bootstrapUsers: resolvePasswordHash(user, hasher)
            bootstrapUsers->>storage: updateUser(tenantId, existing.id, toUpdateUser(...))
            storage-->>bootstrapUsers: updated TenantScoped AdminUser
            bootstrapUsers-->>bootstrapUsers: push updated
        end
    end

    bootstrapUsers->>resolveStorage: close?() [finally]
    bootstrapUsers-->>Caller: BootstrapUsersResult { created, updated, unchanged, users }

Loading

_{Reviews (2): Last reviewed commit: "feat: add auth user bootstrap helper" | Re-trigger Greptile}