@govcore/setup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Allred
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/chunk-PZIHAYWT.js

@@ -0,0 +1,96 @@
+// src/index.ts
+import { randomUUID } from "crypto";
+import postgres from "postgres";
+import { organizations, users } from "@govcore/schema";
+import { slugify, upsertMembership } from "@govcore/tenancy";
+import { hashPassword, validatePassword } from "@govcore/auth";
+import { writeAuditLog } from "@govcore/audit";
+
+// src/identifier.ts
+var IDENTIFIER_RE = /^[a-z_][a-z0-9_]*$/i;
+function assertSafeIdentifier(name, kind) {
+  if (!IDENTIFIER_RE.test(name)) {
+    throw new Error(`Unsafe ${kind} identifier ${JSON.stringify(name)} \u2014 expected /^[A-Za-z_][A-Za-z0-9_]*$/`);
+  }
+}
+
+// src/index.ts
+async function provisionRuntimeRole(opts) {
+  assertSafeIdentifier(opts.role, "role");
+  const schemas = opts.schemas ?? ["govcore"];
+  schemas.forEach((s) => assertSafeIdentifier(s, "schema"));
+  const log = opts.log ?? (() => {
+  });
+  const escapedPassword = opts.password.replace(/'/g, "''");
+  const sql = postgres(opts.connectionString, { max: 1 });
+  try {
+    await sql.unsafe(
+      `DO $$ BEGIN CREATE ROLE ${opts.role} LOGIN PASSWORD '${escapedPassword}';
+       EXCEPTION WHEN duplicate_object THEN NULL; END $$;`
+    );
+    for (const schema of schemas) {
+      await sql.unsafe(`GRANT USAGE ON SCHEMA ${schema} TO ${opts.role}`);
+      await sql.unsafe(`GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ${schema} TO ${opts.role}`);
+      await sql.unsafe(`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${schema} TO ${opts.role}`);
+      await sql.unsafe(
+        `ALTER DEFAULT PRIVILEGES IN SCHEMA ${schema} GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${opts.role}`
+      );
+      await sql.unsafe(
+        `ALTER DEFAULT PRIVILEGES IN SCHEMA ${schema} GRANT USAGE, SELECT ON SEQUENCES TO ${opts.role}`
+      );
+      log(`govcore-setup: granted ${opts.role} on schema ${schema}`);
+    }
+  } finally {
+    await sql.end();
+  }
+}
+async function bootstrap(db, opts) {
+  const name = opts.organization.name.trim();
+  const email = opts.admin.email.trim().toLowerCase();
+  if (!name || !email || !opts.admin.password) {
+    return { ok: false, reason: "missing-fields" };
+  }
+  const validation = validatePassword(opts.admin.password, opts.policy);
+  if (!validation.valid) return { ok: false, reason: "weak-password", message: validation.message };
+  const [existing] = await db.select({ id: organizations.id }).from(organizations).limit(1);
+  if (existing) return { ok: false, reason: "already-bootstrapped" };
+  const adminRole = opts.adminRole ?? "admin";
+  const slug = opts.organization.slug?.trim() || slugify(name);
+  const passwordHash = await hashPassword(opts.admin.password);
+  const adminUserId = randomUUID();
+  const result = await db.transaction(async (tx) => {
+    const [org] = await tx.insert(organizations).values({ name, slug }).returning();
+    await tx.insert(users).values({
+      id: adminUserId,
+      organizationId: org.id,
+      email,
+      name: opts.admin.name?.trim() || null,
+      passwordHash,
+      role: adminRole,
+      instanceRole: "instance_admin"
+    });
+    await upsertMembership(tx, {
+      userId: adminUserId,
+      organizationId: org.id,
+      role: adminRole,
+      isPrimary: true
+    });
+    await writeAuditLog(tx, {
+      action: "platform.bootstrap",
+      entityType: "organization",
+      entityId: org.id,
+      organizationId: org.id,
+      userId: adminUserId,
+      after: { organization: name, slug, admin: email, instanceRole: "instance_admin" }
+    });
+    return { organizationId: org.id, adminUserId };
+  });
+  return { ok: true, ...result };
+}
+
+export {
+  assertSafeIdentifier,
+  provisionRuntimeRole,
+  bootstrap
+};
+//# sourceMappingURL=chunk-PZIHAYWT.js.map

package/dist/chunk-PZIHAYWT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/identifier.ts"],"sourcesContent":["// @govcore/setup — first-run bootstrap for an empty instance.\n//\n// Every consumer reinvents this: GovCRM's seed.ts and GovEA's setup action both\n// (a) provision the non-owner runtime role + grants (the two-role split — getting\n// the grants wrong silently breaks RLS or the app) and (b) create the first org +\n// instance-admin so the instance is usable at all. Both are owner/superuser-run,\n// day-one operations. `bootstrap` refuses to run against a non-empty instance, so\n// it is safe to leave wired into a deploy step.\n//\n// Composes the invariant-bearing helpers (password hashing/policy, membership\n// write-sync, audit) rather than re-hand-rolling them — only the org+admin insert\n// is direct, because at first run there is no prior actor and the whole thing must\n// be one transaction.\n\nimport { randomUUID } from 'node:crypto'\nimport postgres from 'postgres'\nimport { organizations, users, type GovcoreDb } from '@govcore/schema'\nimport { slugify, upsertMembership } from '@govcore/tenancy'\nimport { hashPassword, validatePassword, type PasswordPolicy } from '@govcore/auth'\nimport { writeAuditLog } from '@govcore/audit'\nimport { assertSafeIdentifier } from './identifier'\n\nexport { assertSafeIdentifier } from './identifier'\n\nexport interface ProvisionRuntimeRoleOptions {\n  /** Owner/superuser connection string — role creation and GRANT are DDL. */\n  connectionString: string\n  /** The non-owner runtime role to create (RLS binds it). */\n  role: string\n  /** Login password for the role. */\n  password: string\n  /** Schemas to grant DML + default privileges on. Default `['govcore']`. */\n  schemas?: string[]\n  log?: (message: string) => void\n}\n\n/**\n * Create the non-owner runtime role (idempotent) and grant it DML on the given\n * schemas, including **default privileges** so tables created later (e.g. the\n * content engine's compiled tables) are reachable without re-granting. This is\n * the role the app connects as — it must NOT be a superuser, so RLS binds it\n * (see @govcore/auth's `authDb` for why login still needs a separate pool).\n *\n * Content-engine consumers pass `schemas: ['govcore', 'content']` once the\n * `content` schema exists.\n */\nexport async function provisionRuntimeRole(opts: ProvisionRuntimeRoleOptions): Promise<void> {\n  assertSafeIdentifier(opts.role, 'role')\n  const schemas = opts.schemas ?? ['govcore']\n  schemas.forEach((s) => assertSafeIdentifier(s, 'schema'))\n  const log = opts.log ?? (() => {})\n  const escapedPassword = opts.password.replace(/'/g, \"''\")\n\n  const sql = postgres(opts.connectionString, { max: 1 })\n  try {\n    await sql.unsafe(\n      `DO $$ BEGIN CREATE ROLE ${opts.role} LOGIN PASSWORD '${escapedPassword}';\n       EXCEPTION WHEN duplicate_object THEN NULL; END $$;`,\n    )\n    for (const schema of schemas) {\n      await sql.unsafe(`GRANT USAGE ON SCHEMA ${schema} TO ${opts.role}`)\n      await sql.unsafe(`GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ${schema} TO ${opts.role}`)\n      await sql.unsafe(`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${schema} TO ${opts.role}`)\n      await sql.unsafe(\n        `ALTER DEFAULT PRIVILEGES IN SCHEMA ${schema} GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${opts.role}`,\n      )\n      await sql.unsafe(\n        `ALTER DEFAULT PRIVILEGES IN SCHEMA ${schema} GRANT USAGE, SELECT ON SEQUENCES TO ${opts.role}`,\n      )\n      log(`govcore-setup: granted ${opts.role} on schema ${schema}`)\n    }\n  } finally {\n    await sql.end()\n  }\n}\n\nexport interface BootstrapOptions {\n  organization: { name: string; slug?: string }\n  admin: { email: string; name?: string; password: string }\n  /** Org role for the first admin. Default `admin`. */\n  adminRole?: string\n  /** Password policy the initial password must satisfy. */\n  policy?: PasswordPolicy\n}\n\nexport type BootstrapResult =\n  | { ok: true; organizationId: string; adminUserId: string }\n  | { ok: false; reason: 'already-bootstrapped' | 'missing-fields' | 'weak-password'; message?: string }\n\n/**\n * Create the first organization and its instance-admin on an **empty** instance.\n * Refuses (returns `already-bootstrapped`) if any organization already exists, so\n * it is safe to run repeatedly / leave in a deploy step. Runs as the owner —\n * inserting the first user predates any tenant GUC, which the runtime role's\n * FORCE-RLS would reject.\n *\n * The first admin is the actor of its own creation (self-bootstrap), audited as\n * `platform.bootstrap`. The password is never in the audit payload.\n */\nexport async function bootstrap(db: GovcoreDb, opts: BootstrapOptions): Promise<BootstrapResult> {\n  const name = opts.organization.name.trim()\n  const email = opts.admin.email.trim().toLowerCase()\n  if (!name || !email || !opts.admin.password) {\n    return { ok: false, reason: 'missing-fields' }\n  }\n  const validation = validatePassword(opts.admin.password, opts.policy)\n  if (!validation.valid) return { ok: false, reason: 'weak-password', message: validation.message }\n\n  const [existing] = await db.select({ id: organizations.id }).from(organizations).limit(1)\n  if (existing) return { ok: false, reason: 'already-bootstrapped' }\n\n  const adminRole = opts.adminRole ?? 'admin'\n  const slug = opts.organization.slug?.trim() || slugify(name)\n  const passwordHash = await hashPassword(opts.admin.password)\n  const adminUserId = randomUUID()\n\n  const result = await db.transaction(async (tx) => {\n    const [org] = await tx.insert(organizations).values({ name, slug }).returning()\n    await tx\n      .insert(users)\n      .values({\n        id: adminUserId,\n        organizationId: org.id,\n        email,\n        name: opts.admin.name?.trim() || null,\n        passwordHash,\n        role: adminRole,\n        instanceRole: 'instance_admin',\n      })\n    await upsertMembership(tx, {\n      userId: adminUserId,\n      organizationId: org.id,\n      role: adminRole,\n      isPrimary: true,\n    })\n    await writeAuditLog(tx, {\n      action: 'platform.bootstrap',\n      entityType: 'organization',\n      entityId: org.id,\n      organizationId: org.id,\n      userId: adminUserId,\n      after: { organization: name, slug, admin: email, instanceRole: 'instance_admin' },\n    })\n    return { organizationId: org.id, adminUserId }\n  })\n  return { ok: true, ...result }\n}\n","// Pure SQL-identifier validation, kept in its own module (no heavy imports) so\n// it is unit-testable without loading the DB/auth stack.\n\n/** SQL identifiers (role, schema) are interpolated into DDL, so validate them. */\nconst IDENTIFIER_RE = /^[a-z_][a-z0-9_]*$/i\n\n/** Throw unless `name` is a safe SQL identifier (letters/digits/underscore, not digit-leading). */\nexport function assertSafeIdentifier(name: string, kind: string): void {\n  if (!IDENTIFIER_RE.test(name)) {\n    throw new Error(`Unsafe ${kind} identifier ${JSON.stringify(name)} — expected /^[A-Za-z_][A-Za-z0-9_]*$/`)\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1,35 @@
+import { BootstrapResult } from './index.js';
+import '@govcore/schema';
+import '@govcore/auth';
+
+interface RunSetupOptions {
+    /** Owner/superuser connection string. All three steps are owner operations. */
+    connectionString: string;
+    /** Optional: provision a non-owner runtime role + grants (the two-role split). */
+    runtimeRole?: {
+        role: string;
+        password: string;
+        schemas?: string[];
+    };
+    /** The first organization + instance-admin to create (skipped if already bootstrapped). */
+    organization: {
+        name: string;
+        slug?: string;
+    };
+    admin: {
+        email: string;
+        name?: string;
+        password: string;
+    };
+    adminRole?: string;
+    log?: (message: string) => void;
+}
+interface RunSetupResult {
+    migrationsApplied: string[];
+    runtimeRoleProvisioned: boolean;
+    bootstrap: BootstrapResult;
+}
+/** Migrate → (optional) provision runtime role → bootstrap. Idempotent end to end. */
+declare function runSetup(opts: RunSetupOptions): Promise<RunSetupResult>;
+
+export { type RunSetupOptions, type RunSetupResult, runSetup };

package/dist/cli.js

@@ -0,0 +1,84 @@
+import {
+  bootstrap,
+  provisionRuntimeRole
+} from "./chunk-PZIHAYWT.js";
+
+// src/cli.ts
+import postgres from "postgres";
+import { drizzle } from "drizzle-orm/postgres-js";
+import { migrate } from "@govcore/schema/migrate";
+async function runSetup(opts) {
+  const log = opts.log ?? ((m) => console.log(m));
+  const { applied } = await migrate({ connectionString: opts.connectionString, log });
+  let runtimeRoleProvisioned = false;
+  if (opts.runtimeRole) {
+    await provisionRuntimeRole({
+      connectionString: opts.connectionString,
+      role: opts.runtimeRole.role,
+      password: opts.runtimeRole.password,
+      schemas: opts.runtimeRole.schemas,
+      log
+    });
+    runtimeRoleProvisioned = true;
+  }
+  const client = postgres(opts.connectionString, { max: 1 });
+  try {
+    const result = await bootstrap(drizzle(client), {
+      organization: opts.organization,
+      admin: opts.admin,
+      adminRole: opts.adminRole
+    });
+    if (result.ok) log(`govcore-setup: bootstrapped org ${result.organizationId}`);
+    else log(`govcore-setup: bootstrap skipped (${result.reason})`);
+    return { migrationsApplied: applied, runtimeRoleProvisioned, bootstrap: result };
+  } finally {
+    await client.end();
+  }
+}
+function optionsFromEnv() {
+  const env = process.env;
+  const connectionString = env.GOVCORE_SETUP_DATABASE_URL || env.DATABASE_URL;
+  const require_ = (key) => {
+    const v = env[key];
+    if (!v) {
+      console.error(`govcore-setup: missing required env var ${key}`);
+      process.exit(2);
+    }
+    return v;
+  };
+  if (!connectionString) {
+    console.error("govcore-setup: set GOVCORE_SETUP_DATABASE_URL or DATABASE_URL (owner/superuser)");
+    process.exit(2);
+  }
+  const runtimeRole = env.GOVCORE_APP_ROLE ? {
+    role: env.GOVCORE_APP_ROLE,
+    password: require_("GOVCORE_APP_PASSWORD"),
+    schemas: env.GOVCORE_APP_SCHEMAS?.split(",").map((s) => s.trim())
+  } : void 0;
+  return {
+    connectionString,
+    runtimeRole,
+    organization: { name: require_("GOVCORE_ORG_NAME"), slug: env.GOVCORE_ORG_SLUG },
+    admin: {
+      email: require_("GOVCORE_ADMIN_EMAIL"),
+      name: env.GOVCORE_ADMIN_NAME,
+      password: require_("GOVCORE_ADMIN_PASSWORD")
+    },
+    adminRole: env.GOVCORE_ADMIN_ROLE
+  };
+}
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  runSetup(optionsFromEnv()).then((r) => {
+    if (!r.bootstrap.ok && r.bootstrap.reason !== "already-bootstrapped") {
+      console.error(`govcore-setup: bootstrap failed (${r.bootstrap.reason})`);
+      process.exit(1);
+    }
+  }).catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+export {
+  runSetup
+};
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["// @govcore/setup/cli — the govcore-setup runner + bin.\n//\n// One idempotent command from an empty database to first login: migrate →\n// provision the runtime role → bootstrap the first org/admin. Runs as the\n// OWNER/superuser (all three steps are owner operations). Mirrors govcore-migrate's\n// bin pattern (no shebang; guarded by the import.meta.url check).\n\nimport postgres from 'postgres'\nimport { drizzle } from 'drizzle-orm/postgres-js'\nimport { migrate } from '@govcore/schema/migrate'\nimport { bootstrap, provisionRuntimeRole, type BootstrapResult } from './index'\n\nexport interface RunSetupOptions {\n  /** Owner/superuser connection string. All three steps are owner operations. */\n  connectionString: string\n  /** Optional: provision a non-owner runtime role + grants (the two-role split). */\n  runtimeRole?: { role: string; password: string; schemas?: string[] }\n  /** The first organization + instance-admin to create (skipped if already bootstrapped). */\n  organization: { name: string; slug?: string }\n  admin: { email: string; name?: string; password: string }\n  adminRole?: string\n  log?: (message: string) => void\n}\n\nexport interface RunSetupResult {\n  migrationsApplied: string[]\n  runtimeRoleProvisioned: boolean\n  bootstrap: BootstrapResult\n}\n\n/** Migrate → (optional) provision runtime role → bootstrap. Idempotent end to end. */\nexport async function runSetup(opts: RunSetupOptions): Promise<RunSetupResult> {\n  const log = opts.log ?? ((m: string) => console.log(m))\n\n  const { applied } = await migrate({ connectionString: opts.connectionString, log })\n\n  let runtimeRoleProvisioned = false\n  if (opts.runtimeRole) {\n    await provisionRuntimeRole({\n      connectionString: opts.connectionString,\n      role: opts.runtimeRole.role,\n      password: opts.runtimeRole.password,\n      schemas: opts.runtimeRole.schemas,\n      log,\n    })\n    runtimeRoleProvisioned = true\n  }\n\n  const client = postgres(opts.connectionString, { max: 1 })\n  try {\n    const result = await bootstrap(drizzle(client), {\n      organization: opts.organization,\n      admin: opts.admin,\n      adminRole: opts.adminRole,\n    })\n    if (result.ok) log(`govcore-setup: bootstrapped org ${result.organizationId}`)\n    else log(`govcore-setup: bootstrap skipped (${result.reason})`)\n    return { migrationsApplied: applied, runtimeRoleProvisioned, bootstrap: result }\n  } finally {\n    await client.end()\n  }\n}\n\n/** Read the runner options from environment variables (for the bin). */\nfunction optionsFromEnv(): RunSetupOptions {\n  const env = process.env\n  const connectionString = env.GOVCORE_SETUP_DATABASE_URL || env.DATABASE_URL\n  const require_ = (key: string): string => {\n    const v = env[key]\n    if (!v) {\n      console.error(`govcore-setup: missing required env var ${key}`)\n      process.exit(2)\n    }\n    return v\n  }\n  if (!connectionString) {\n    console.error('govcore-setup: set GOVCORE_SETUP_DATABASE_URL or DATABASE_URL (owner/superuser)')\n    process.exit(2)\n  }\n  const runtimeRole = env.GOVCORE_APP_ROLE\n    ? {\n        role: env.GOVCORE_APP_ROLE,\n        password: require_('GOVCORE_APP_PASSWORD'),\n        schemas: env.GOVCORE_APP_SCHEMAS?.split(',').map((s) => s.trim()),\n      }\n    : undefined\n  return {\n    connectionString,\n    runtimeRole,\n    organization: { name: require_('GOVCORE_ORG_NAME'), slug: env.GOVCORE_ORG_SLUG },\n    admin: {\n      email: require_('GOVCORE_ADMIN_EMAIL'),\n      name: env.GOVCORE_ADMIN_NAME,\n      password: require_('GOVCORE_ADMIN_PASSWORD'),\n    },\n    adminRole: env.GOVCORE_ADMIN_ROLE,\n  }\n}\n\n// Run when invoked as the `govcore-setup` bin.\nif (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {\n  runSetup(optionsFromEnv())\n    .then((r) => {\n      if (!r.bootstrap.ok && r.bootstrap.reason !== 'already-bootstrapped') {\n        console.error(`govcore-setup: bootstrap failed (${r.bootstrap.reason})`)\n        process.exit(1)\n      }\n    })\n    .catch((err) => {\n      console.error(err)\n      process.exit(1)\n    })\n}\n"],"mappings":";;;;;;AAOA,OAAO,cAAc;AACrB,SAAS,eAAe;AACxB,SAAS,eAAe;AAsBxB,eAAsB,SAAS,MAAgD;AAC7E,QAAM,MAAM,KAAK,QAAQ,CAAC,MAAc,QAAQ,IAAI,CAAC;AAErD,QAAM,EAAE,QAAQ,IAAI,MAAM,QAAQ,EAAE,kBAAkB,KAAK,kBAAkB,IAAI,CAAC;AAElF,MAAI,yBAAyB;AAC7B,MAAI,KAAK,aAAa;AACpB,UAAM,qBAAqB;AAAA,MACzB,kBAAkB,KAAK;AAAA,MACvB,MAAM,KAAK,YAAY;AAAA,MACvB,UAAU,KAAK,YAAY;AAAA,MAC3B,SAAS,KAAK,YAAY;AAAA,MAC1B;AAAA,IACF,CAAC;AACD,6BAAyB;AAAA,EAC3B;AAEA,QAAM,SAAS,SAAS,KAAK,kBAAkB,EAAE,KAAK,EAAE,CAAC;AACzD,MAAI;AACF,UAAM,SAAS,MAAM,UAAU,QAAQ,MAAM,GAAG;AAAA,MAC9C,cAAc,KAAK;AAAA,MACnB,OAAO,KAAK;AAAA,MACZ,WAAW,KAAK;AAAA,IAClB,CAAC;AACD,QAAI,OAAO,GAAI,KAAI,mCAAmC,OAAO,cAAc,EAAE;AAAA,QACxE,KAAI,qCAAqC,OAAO,MAAM,GAAG;AAC9D,WAAO,EAAE,mBAAmB,SAAS,wBAAwB,WAAW,OAAO;AAAA,EACjF,UAAE;AACA,UAAM,OAAO,IAAI;AAAA,EACnB;AACF;AAGA,SAAS,iBAAkC;AACzC,QAAM,MAAM,QAAQ;AACpB,QAAM,mBAAmB,IAAI,8BAA8B,IAAI;AAC/D,QAAM,WAAW,CAAC,QAAwB;AACxC,UAAM,IAAI,IAAI,GAAG;AACjB,QAAI,CAAC,GAAG;AACN,cAAQ,MAAM,2CAA2C,GAAG,EAAE;AAC9D,cAAQ,KAAK,CAAC;AAAA,IAChB;AACA,WAAO;AAAA,EACT;AACA,MAAI,CAAC,kBAAkB;AACrB,YAAQ,MAAM,iFAAiF;AAC/F,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,QAAM,cAAc,IAAI,mBACpB;AAAA,IACE,MAAM,IAAI;AAAA,IACV,UAAU,SAAS,sBAAsB;AAAA,IACzC,SAAS,IAAI,qBAAqB,MAAM,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC;AAAA,EAClE,IACA;AACJ,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,cAAc,EAAE,MAAM,SAAS,kBAAkB,GAAG,MAAM,IAAI,iBAAiB;AAAA,IAC/E,OAAO;AAAA,MACL,OAAO,SAAS,qBAAqB;AAAA,MACrC,MAAM,IAAI;AAAA,MACV,UAAU,SAAS,wBAAwB;AAAA,IAC7C;AAAA,IACA,WAAW,IAAI;AAAA,EACjB;AACF;AAGA,IAAI,QAAQ,KAAK,CAAC,KAAK,YAAY,QAAQ,UAAU,QAAQ,KAAK,CAAC,CAAC,IAAI;AACtE,WAAS,eAAe,CAAC,EACtB,KAAK,CAAC,MAAM;AACX,QAAI,CAAC,EAAE,UAAU,MAAM,EAAE,UAAU,WAAW,wBAAwB;AACpE,cAAQ,MAAM,oCAAoC,EAAE,UAAU,MAAM,GAAG;AACvE,cAAQ,KAAK,CAAC;AAAA,IAChB;AAAA,EACF,CAAC,EACA,MAAM,CAAC,QAAQ;AACd,YAAQ,MAAM,GAAG;AACjB,YAAQ,KAAK,CAAC;AAAA,EAChB,CAAC;AACL;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { GovcoreDb } from '@govcore/schema';
+import { PasswordPolicy } from '@govcore/auth';
+
+/** Throw unless `name` is a safe SQL identifier (letters/digits/underscore, not digit-leading). */
+declare function assertSafeIdentifier(name: string, kind: string): void;
+
+interface ProvisionRuntimeRoleOptions {
+    /** Owner/superuser connection string — role creation and GRANT are DDL. */
+    connectionString: string;
+    /** The non-owner runtime role to create (RLS binds it). */
+    role: string;
+    /** Login password for the role. */
+    password: string;
+    /** Schemas to grant DML + default privileges on. Default `['govcore']`. */
+    schemas?: string[];
+    log?: (message: string) => void;
+}
+/**
+ * Create the non-owner runtime role (idempotent) and grant it DML on the given
+ * schemas, including **default privileges** so tables created later (e.g. the
+ * content engine's compiled tables) are reachable without re-granting. This is
+ * the role the app connects as — it must NOT be a superuser, so RLS binds it
+ * (see @govcore/auth's `authDb` for why login still needs a separate pool).
+ *
+ * Content-engine consumers pass `schemas: ['govcore', 'content']` once the
+ * `content` schema exists.
+ */
+declare function provisionRuntimeRole(opts: ProvisionRuntimeRoleOptions): Promise<void>;
+interface BootstrapOptions {
+    organization: {
+        name: string;
+        slug?: string;
+    };
+    admin: {
+        email: string;
+        name?: string;
+        password: string;
+    };
+    /** Org role for the first admin. Default `admin`. */
+    adminRole?: string;
+    /** Password policy the initial password must satisfy. */
+    policy?: PasswordPolicy;
+}
+type BootstrapResult = {
+    ok: true;
+    organizationId: string;
+    adminUserId: string;
+} | {
+    ok: false;
+    reason: 'already-bootstrapped' | 'missing-fields' | 'weak-password';
+    message?: string;
+};
+/**
+ * Create the first organization and its instance-admin on an **empty** instance.
+ * Refuses (returns `already-bootstrapped`) if any organization already exists, so
+ * it is safe to run repeatedly / leave in a deploy step. Runs as the owner —
+ * inserting the first user predates any tenant GUC, which the runtime role's
+ * FORCE-RLS would reject.
+ *
+ * The first admin is the actor of its own creation (self-bootstrap), audited as
+ * `platform.bootstrap`. The password is never in the audit payload.
+ */
+declare function bootstrap(db: GovcoreDb, opts: BootstrapOptions): Promise<BootstrapResult>;
+
+export { type BootstrapOptions, type BootstrapResult, type ProvisionRuntimeRoleOptions, assertSafeIdentifier, bootstrap, provisionRuntimeRole };

package/dist/index.js

@@ -0,0 +1,11 @@
+import {
+  assertSafeIdentifier,
+  bootstrap,
+  provisionRuntimeRole
+} from "./chunk-PZIHAYWT.js";
+export {
+  assertSafeIdentifier,
+  bootstrap,
+  provisionRuntimeRole
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@govcore/setup",
+  "version": "0.1.0",
+  "description": "First-run bootstrap: runtime-role provisioning + first org/admin, idempotent",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "bin": {
+    "govcore-setup": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "postgres": "^3.4.0",
+    "@govcore/auth": "0.4.0",
+    "@govcore/schema": "0.3.0",
+    "@govcore/audit": "0.1.3",
+    "@govcore/tenancy": "0.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "tsup": "^8.3.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "tsup": {
+    "entry": [
+      "src/index.ts",
+      "src/cli.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "dts": true,
+    "clean": true,
+    "sourcemap": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
+}