@devdogsuga/backstage 0.1.0

package/env.ts

@@ -0,0 +1,163 @@
+/**
+ * The operator manifest: keys no app schema reads. They belong to the person
+ * running devtools, pushing secrets, deploying.
+ *
+ * NOTHING IMPORTS THIS FILE at runtime. Like the other package-root manifests
+ * it exists for the registry's consumers: the completeness test, the
+ * `.env.example` generator, the `env push` routing. The package's `typecheck`
+ * script is what keeps the metadata honest.
+ *
+ * This is also where the `never-store` credential is declared, and the
+ * classification is the whole point. It is the most sensitive value in the
+ * repository, refused storage because storing it defeats the thing it
+ * protects. See the long-form reasoning in `src/bws/environments.ts`.
+ */
+import { declare, define } from "@devdogsuga/env";
+import { z } from "zod";
+
+declare({
+  source: "devtools",
+  server: {
+    // Everything here is optional: these are operator credentials, and an
+    // app or CI that cannot boot without one of them would be wrong.
+    // Presence is checked at the point of use, with a named refusal.
+    //
+    // Local .env storage was refused here until 2026-08-19 and is now
+    // OFFERED (the prompt's default save destination), by decision. What
+    // held, holds: the refusals that matter are the REMOTE ones. `env push`
+    // refuses this key by name, `pull` will not write it back, and `audit`
+    // errors on any remote copy, because one
+    // `${{ secrets.BWS_ACCESS_TOKEN }}` would hand CI every secret we hold,
+    // and storing it in a Bitwarden project is a key locked inside the box
+    // it opens. A gitignored .env on the operator's own machine is neither
+    // store, and it already holds credentials of comparable reach after any
+    // `env pull --target production`. Note `with-env` loads .env for every
+    // wrapped command, dev servers included; the Password Manager vault
+    // remains the save destination for anyone who minds that.
+    BWS_ACCESS_TOKEN: define(z.string().min(1).optional(), {
+      doc:
+        "Unlocks every Bitwarden Secrets Manager project, so it must never " +
+        "reach a remote store: never IN one of those projects (a key locked " +
+        "inside the box it opens), never synced to GitHub (would hand CI " +
+        "every secret we hold) -- push refuses it by name. Lives on the " +
+        "operator's own machine: this file (the prompt offers to save it " +
+        "here) or their Password Manager vault.",
+      scope: "environment",
+      secrecy: "never-store",
+    }),
+    SUPABASE_ACCESS_TOKEN: define(z.string().min(1).optional(), {
+      doc:
+        "A Supabase personal access token, carrying full account privileges " +
+        "across both Supabase organizations. Only `supabase config push` " +
+        "needs it -- the one mutation with no dry run -- so in GitHub it " +
+        "reaches the production-apply environment only, behind required " +
+        "reviewers.",
+      scope: "environment",
+      secrecy: "secret",
+      tier: "apply",
+      commented: true,
+    }),
+    // Devops-only, per the model doc. It appears in no contributor flow:
+    // `pnpm dev`, `pnpm build` and every test suite run without it, so its
+    // absence can never fail validation or block a boot.
+    CLOUDFLARE_API_TOKEN: define(z.string().min(1).optional(), {
+      doc:
+        "Deploys Workers and sets bindings; only devops hold it. Deploy " +
+        "scripts must check for it first and exit naming who to ask, rather " +
+        "than falling into wrangler's interactive browser OAuth.",
+      scope: "environment",
+      secrecy: "secret",
+      commented: true,
+    }),
+    // The value is committed as the example: one account, public identifier
+    // (it is in every dashboard URL), same in every environment.
+    CLOUDFLARE_ACCOUNT_ID: define(
+      z
+        .string()
+        .regex(/^[0-9a-f]{32}$/)
+        .optional(),
+      {
+        doc:
+          "The Cloudflare account the Workers live in. Wrangler honors this " +
+          "public identifier in the environment; each app's wrangler config " +
+          "pins the same value so scoped deploy tokens never need account " +
+          "discovery. Identifies, does not authorize — every capability is " +
+          "the token's.",
+        scope: "default",
+        secrecy: "public",
+        example: "61d185ff419ef7bd5bd4b3d314081a49",
+      },
+    ),
+    // Read only by the deploy workflow's Sentry release step and the deploy
+    // smoke test, never by an app. Without the token, deploys skip the release
+    // and its source-map upload with a warning. With it, a failed upload fails
+    // the deploy.
+    SENTRY_AUTH_TOKEN: define(z.string().min(1).optional(), {
+      doc:
+        "A Sentry organization auth token. Deploys use it to create each " +
+        "release and upload its source maps, and the smoke test uses it to " +
+        "read cron check-ins. One token serves every environment.",
+      scope: "environment",
+      secrecy: "secret",
+      commented: true,
+    }),
+    SENTRY_ORG: define(z.string().min(1).optional(), {
+      doc:
+        "The Sentry organization slug the release step and smoke test " +
+        "address. Identifies, does not authorize.",
+      scope: "default",
+      secrecy: "public",
+      example: "devdogsuga",
+    }),
+    // Developer-scoped even though the VALUE is org-wide: only operators
+    // running `env pull/push/audit` on their own machines read it, no app and
+    // no CI job does, and developer scope is what keeps a purely local input
+    // out of every routed set. A public identifier: it names the org and
+    // authorizes nothing, every capability comes from BWS_ACCESS_TOKEN.
+    BWS_ORG_ID: define(z.uuid().optional(), {
+      doc:
+        "The Bitwarden organization id, needed since the Secrets Manager " +
+        "SDK replaced the bws binary (2026-08-19): every SDK call addresses " +
+        "the org explicitly, and nothing in its surface discovers it from " +
+        "the token. A public UUID -- it is in the Secrets Manager URL " +
+        "(bitwarden.com/#/sm/<org-id>/...) -- that identifies and does not " +
+        "authorize. Leave it unset and the first Secrets Manager command " +
+        "asks, then saves it here.",
+      scope: "developer",
+      secrecy: "public",
+    }),
+    DEV_VPN_HOST: define(z.string().min(1).optional(), {
+      doc:
+        "One machine's VPN IP, for testing on a phone over VPN (the HMR " +
+        "origin). Meaningless to anyone else, so never pushed anywhere.",
+      scope: "developer",
+      secrecy: "public",
+    }),
+    SKIP_ENV_VALIDATION: define(z.string().optional(), {
+      doc:
+        "Any non-empty value skips env-schema validation, for builds that " +
+        "run without secrets -- CI and Docker. Never set it locally: it " +
+        "turns misconfiguration from a build error into a runtime surprise.",
+      scope: "default",
+      secrecy: "public",
+      commented: true,
+    }),
+    // No DEVTOOLS_SENTRY_DSN here: the DSN is baked in at publish time, not
+    // configured by the consumer (see src/telemetry.ts).
+    //
+    // Reporting is ON by default in a published build -- unlike
+    // every other telemetry surface in this workspace, which a consumer
+    // opts INTO by configuring a DSN, this one an operator opts OUT of.
+    // `"0"` is the one recognized value; anything else, including unset,
+    // leaves reporting on. Developer-scoped: it is a per-machine (or
+    // per-job) preference, never something `env push` should route
+    // anywhere.
+    DEVTOOLS_TELEMETRY: define(z.string().optional(), {
+      doc:
+        'Set to "0" to opt out of devtools\' Sentry error reporting (on by ' +
+        "default in published builds). See src/telemetry.ts.",
+      scope: "developer",
+      secrecy: "public",
+    }),
+  },
+});

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@devdogsuga/backstage",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Officer and production CLI for DevDogsUGA: deploys, env sync with Bitwarden and GitHub, the migration planner role, club graphics and QR codes, GitHub rulesets and settings, and the newsletter. Ships built JS; run it anywhere with `pnpm dlx @devdogsuga/backstage` (no checkout needed to start; commands that read a checkout say so).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DevDogsUGA/Backstage.git",
+    "directory": "packages/backstage"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "backstage": "./bin/backstage.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "env.ts"
+  ],
+  "dependencies": {
+    "@bitwarden/cli": "2026.7.0",
+    "@bitwarden/sdk-napi": "1.0.0",
+    "@clack/prompts": "1.7.0",
+    "@resvg/resvg-js": "^2.6.2",
+    "@sentry/node": "10.75.1",
+    "@supabase/supabase-js": "^2.112.3",
+    "dotenv": "^17.4.2",
+    "postgres": "^3.4.9",
+    "react": "^19.2.8",
+    "satori": "^0.33.4",
+    "sharp": "0.35.3",
+    "tsx": "^4.23.12",
+    "typescript": "^6.0.3",
+    "zod": "4.4.3",
+    "@devdogsuga/brand": "0.1.4",
+    "@devdogsuga/events": "0.1.4",
+    "@devdogsuga/newsletter": "0.1.7",
+    "@devdogsuga/telemetry": "0.1.2"
+  },
+  "peerDependencies": {
+    "@devdogsuga/db": "*",
+    "@devdogsuga/env": "*"
+  },
+  "peerDependenciesMeta": {
+    "@devdogsuga/db": {
+      "optional": true
+    },
+    "@devdogsuga/env": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^9.39.5",
+    "tsdown": "^0.23.0",
+    "vitest": "^4.1.11",
+    "@devdogsuga/cli-core": "0.0.0",
+    "@devdogsuga/config": "0.1.0",
+    "@devdogsuga/db": "0.1.2",
+    "@devdogsuga/env": "0.1.4"
+  },
+  "scripts": {
+    "build": "tsdown && node scripts/write-build-info.mjs && node ../../scripts/check-bundle-imports.mjs",
+    "cli": "node ./bin/backstage.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:contract": "vitest run --config vitest.contract.config.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
+}