@xpertss/projen-types 0.0.0 → 0.0.2

package/lib/common/drift-check.js

@@ -1,18 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.driftCheckSteps = driftCheckSteps;
-/**
- * Steps that re-run projen and fail the job if the generated output no
- * longer matches what's committed - i.e. someone hand-edited a projen
- * managed file (package.json/pom.xml/.github/workflows/*.yml/...) without
- * going through .projenrc.
- */
-function driftCheckSteps(projenCommand = 'npx projen') {
-    return [
-        {
-            name: 'Check for projen drift',
-            run: `${projenCommand}\ngit diff --exit-code`,
-        },
-    ];
-}
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZHJpZnQtY2hlY2suanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvY29tbW9uL2RyaWZ0LWNoZWNrLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBUUEsMENBU0M7QUFmRDs7Ozs7R0FLRztBQUNILFNBQWdCLGVBQWUsQ0FDN0IsYUFBYSxHQUFHLFlBQVk7SUFFNUIsT0FBTztRQUNMO1lBQ0UsSUFBSSxFQUFFLHdCQUF3QjtZQUM5QixHQUFHLEVBQUUsR0FBRyxhQUFhLHdCQUF3QjtTQUM5QztLQUNGLENBQUM7QUFDSixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgZ2l0aHViIH0gZnJvbSAncHJvamVuJztcblxuLyoqXG4gKiBTdGVwcyB0aGF0IHJlLXJ1biBwcm9qZW4gYW5kIGZhaWwgdGhlIGpvYiBpZiB0aGUgZ2VuZXJhdGVkIG91dHB1dCBub1xuICogbG9uZ2VyIG1hdGNoZXMgd2hhdCdzIGNvbW1pdHRlZCAtIGkuZS4gc29tZW9uZSBoYW5kLWVkaXRlZCBhIHByb2plblxuICogbWFuYWdlZCBmaWxlIChwYWNrYWdlLmpzb24vcG9tLnhtbC8uZ2l0aHViL3dvcmtmbG93cy8qLnltbC8uLi4pIHdpdGhvdXRcbiAqIGdvaW5nIHRocm91Z2ggLnByb2plbnJjLlxuICovXG5leHBvcnQgZnVuY3Rpb24gZHJpZnRDaGVja1N0ZXBzKFxuICBwcm9qZW5Db21tYW5kID0gJ25weCBwcm9qZW4nLFxuKTogZ2l0aHViLndvcmtmbG93cy5Kb2JTdGVwW10ge1xuICByZXR1cm4gW1xuICAgIHtcbiAgICAgIG5hbWU6ICdDaGVjayBmb3IgcHJvamVuIGRyaWZ0JyxcbiAgICAgIHJ1bjogYCR7cHJvamVuQ29tbWFuZH1cXG5naXQgZGlmZiAtLWV4aXQtY29kZWAsXG4gICAgfSxcbiAgXTtcbn1cbiJdfQ==

package/spec/npm-publishing-setup.md

@@ -1,150 +0,0 @@
-# npm Publishing Setup — `@xpertss/projen-types`
-
-## Root cause (verified)
-
-The `release_npm` job in `.github/workflows/release.yml` (lines 108–157) publishes via projen's publib:
-
-```yaml
-- name: Release
-  env:
-    NPM_DIST_TAG: latest
-    NPM_REGISTRY: registry.npmjs.org
-    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-    PUBLIB_DRYRUN: ${{ inputs.dry_run }}
-  run: npx '-p' 'publib@latest' 'publib-npm'
-```
-
-The `publib-npm` script (publib@0.3.3, `bin/publib-npm` lines 43–46) exits with:
-
-```
-NPM_TOKEN=<token> or NPM_TRUSTED_PUBLISHER=true is required
-```
-
-when **both** are absent. Current state of the repo:
-
-- GitHub Actions secret `NPM_TOKEN` is **not set** on the repository → expands to empty string
-- `NPM_TRUSTED_PUBLISHER` is not set in the workflow
-- `release_npm` job has only `contents: read` permission — no `id-token: write`, so OIDC is not possible yet
-
-So the job has no credential at all. Exactly one of the two options below fixes it.
-
-## npm's 2026 policy context (affects the choice)
-
-- **November 2025:** legacy (classic) access tokens removed — only **granular access tokens** exist now (mandatory expiry, scoping to package/scope).
-- **January 2027:** direct publishing of new versions **with granular tokens is being removed**. Bypass-2FA + direct-publish tokens are deprecated; npm's stated path for CI is trusted publishing (OIDC) or stage-only tokens + `npm stage publish`.
-- Therefore: the token option is a quick unblock today, but **trusted publishing is the only durable solution**.
-
----
-
-## Option A — `NPM_TOKEN` GitHub secret (granular access token)
-
-Fastest to get working. No code changes — `release.yml` already reads `secrets.NPM_TOKEN`.
-
-### Prerequisites
-
-- An npm user account.
-- For the scoped package `@xpertss/projen-types`: the `@xpertss` npm organization must exist and your account must be a member with rights to publish under that scope. (If the org doesn't exist yet: npmjs.com → Organizations → create it, free tier is fine for a *public* package; restricted/private packages require a paid plan.)
-
-### 1. Create a granular access token (web UI recommended)
-
-1. Log in to npmjs.com.
-2. Avatar (top right) → **Access Tokens** → **Generate New Token**.
-3. Configure:
-   - **Access:** *Read and write (publish and stage)* — required for direct `npm publish`. (A *stage only* token cannot be used here: publib runs `npm publish`, which fails with `E_STAGE_REQUIRED`.)
-   - **Scope:** restrict to the single package `@xpertss/projen-types`.
-   - **Expiry:** mandatory — pick a date, remember to rotate.
-   - **Bypass 2FA:** enable — CI publishing is non-interactive; without this, a 2FA-enabled account will make the publish hang/fail.
-4. **Copy the token** — shown only once.
-
-### 2. Store it in GitHub
-
-1. GitHub → repo `xpertss/projen` → **Settings** → **Secrets and variables** → **Actions**.
-2. **New repository secret** → Name: `NPM_TOKEN` → Value: the token.
-   - Must be a *repository* secret (the workflow references it from the repo, not an environment/org).
-
-### 3. Test
-
-- Actions tab → `release` workflow → **Run workflow** → `dry_run = true`. publib checks the token *before* the dry-run short-circuit, so a valid secret gets past the previous failure point and stops at "Dry run: skipping npm publish".
-- Then trigger a real release (push to `main`, or `Run workflow` without `dry_run`).
-
-### Caveats
-
-- **Access level:** `NPM_ACCESS_LEVEL` is not set anywhere in the generated workflow, and `npm publish` defaults scoped packages to **restricted (private)** — which requires a paid npm plan. If the package is meant to be public, add to `.projenrc.ts`:
-  ```ts
-  project.addFields({ publishConfig: { access: 'public' } });
-  ```
-  and run `npx projen`. `npm publish` honors `publishConfig.access` from the tarball's `package.json`. (Only needed for the first publish of a version; access is fixed per package version.)
-- Tokens expire and must be rotated.
-- **Direct token publishing is removed January 2027** — migrate to Option B before then.
-
----
-
-## Option B — npm Trusted Publishing (OIDC, recommended)
-
-No long-lived secret at all. npm exchanges a short-lived, workflow-scoped OIDC token for a publish credential. Provenance attestations are generated automatically (public repo + public package).
-
-### Requirements
-
-- npm CLI ≥ 11.5.1 / Node ≥ 22.14. The workflow uses `actions/setup-node@v7` with `node-version: lts/*` (Node 24 LTS, npm 11.x) → satisfied. (If you ever pin a Node version in `workflowNodeVersion`, keep it ≥ 22.14.)
-- GitHub-hosted runners (the workflow uses `ubuntu-latest` → OK).
-- `package.json` `repository.url` must match the GitHub repo exactly — it does: `git@github.com:xpertss/projen`.
-- The package must **already exist** on the registry before a trusted publisher can be configured for it (create it via Option A's first publish or a one-off manual `npm publish`).
-
-### 1. Enable it in projen
-
-`release.yml` is projen-generated, so change the source, not the file. In `.projenrc.ts`:
-
-```ts
-const project = new cdk.JsiiProject({
-  ...
-  npmTrustedPublishing: true,   // NEW
-});
-```
-
-Then run `npx projen`. Verified against the installed projen 0.103.23 (`lib/cdk/jsii-build.js:162`, `lib/release/publisher.js:226,269`): this makes the `release_npm` job emit:
-
-- `env: NPM_TRUSTED_PUBLISHER: "true"` (publib then `unset`s `NPM_TOKEN` and skips the token check)
-- `permissions: id-token: write` (required for GitHub to mint OIDC tokens)
-- `NPM_TOKEN` is no longer referenced (it is mutually exclusive with a `npmTokenSecret` option)
-
-Commit `.projenrc.ts` and the regenerated `release.yml`.
-
-### 2. Configure the trusted publisher on npmjs.com
-
-1. npmjs.com → package `@xpertss/projen-types` → **Settings** → **Trusted Publisher** → **Add trusted publisher** → **GitHub Actions**.
-2. Fill in:
-   - **Organization or user:** `xpertss`
-   - **Repository:** `projen`
-   - **Workflow filename:** `release.yml` (filename only, exact case, must live in `.github/workflows/`)
-   - **Environment name:** leave empty
-   - **Allowed actions:** **also allow `npm publish`** — configurations created after 2026-09-03 default to *stage-only* (`npm stage publish`), but publib runs `npm publish`, so direct publish must be explicitly permitted.
-3. npm does **not** validate the configuration when you save it — mismatches only surface at publish time as "Unable to authenticate" (ENEEDAUTH). Double-check the fields.
-
-### 3. Verify
-
-- Push a commit to `main` (or run the workflow) so a real release occurs. The `release_npm` job should complete with "SUCCESS" — no secret involved.
-- Once it works, npm's recommended hardening: package **Settings** → **Publishing access** → *Require two-factor authentication and disallow tokens* → save. This kills token-based publishing entirely while trusted publishing keeps working.
-
-### Failure-mode checklist
-
-| Symptom | Cause |
-|---|---|
-| `ENEEDAUTH` / "Unable to authenticate" | workflow filename or repo/owner field mismatch (case-sensitive); or missing `id-token: write` |
-| `E_STAGE_REQUIRED` | trusted publisher was created stage-only; allow `npm publish` in its allowed actions |
-| Provenance missing | package or repo not public — expected, not an error |
-
----
-
-## Recommendation
-
-1. If the package doesn't exist on npm yet and you need a release **now**: Option A (token) unblocks it in ~10 minutes, including the `publishConfig.access` fix for public visibility.
-2. Do Option B in the same or next session, verify a real publish, then lock down with "disallow tokens" and revoke the token from Option A.
-3. Option A alone must be retired before **January 2027** (direct token publishing removal).
-
-## References
-
-- Workflow: `.github/workflows/release.yml` (job `release_npm`, lines 108–157)
-- publib source: https://github.com/cdklabs/publib — `bin/publib-npm` (v0.3.3)
-- npm token policy: https://docs.npmjs.com/about-access-tokens (granular-only since Nov 2025; direct token publishing removed Jan 2027)
-- npm trusted publishing: https://docs.npmjs.com/trusted-publishers
-- projen trusted publishing: https://projen.io/docs/publishing/trusted-publishing/

package/spec/projen-cdk-spec.md

@@ -1,80 +0,0 @@
-# projen-cdk — Project Spec
-
-## Overview
-
-`projen-cdk` is a projen project-type package (`@cai-projen/projen-cdk`) providing scaffolding for CoxAuto's two AWS CDK/TypeScript project types. Both share the CDK/TypeScript foundation and a manual-dispatch deploy workflow; `CdkAppProject` is `CdkInfraProject` plus a real running application and its data layer.
-
-## Project Types
-
-### 1. `CdkInfraProject`
-- **Purpose:** Pure infrastructure stacks — little or no application code. Reference example: SimulcastAVDelivery.
-- **Typical resources:** CloudFront, Route53, SQS, API Gateway, Cognito, ECR repos, ECS services/clusters standing up externally-built Docker images.
-- **Code:** Usually none, or a small Lambda/handful of Lambdas.
-- **Workflows:** PR-time checks (synth/diff, lint, unit tests on any Lambda code); manual-dispatch deploy per environment.
-
-### 2. `CdkAppProject`
-- **Purpose:** Full TypeScript service applications running behind API Gateway (or similar), with the infra to support them.
-- **Adds on top of `CdkInfraProject`:**
-  - Full TypeScript application source structure (handlers/business logic, not just infra).
-  - Database provisioning + migration tooling.
-  - Same API Gateway/ECS/ECR patterns as type 1, but application-owned rather than accepting arbitrary external images.
-- **Workflows:** Same PR checks as type 1, plus app-level build/test, plus manual-dispatch deploy.
-
-## Shared Components
-
-| Component | Description | Used by |
-|---|---|---|
-| `CdkTypescriptBase` | Base CDK app structure, `cdk.json`, TypeScript config, standard stack layout | 1, 2 |
-| `PrCheckWorkflow` | `cdk synth`/`cdk diff`, lint, unit tests on PR. Also runs `npx projen` and `git diff --exit-code` against generated files (`cdk.json`, `package.json`, `tsconfig.json`, `.github/workflows/*.yml`) to fail the PR if a hand edit drifted from the projen-managed output | 1, 2 |
-| `ManualDeployWorkflow` | Manual-dispatch deploy workflow, environment-parameterized (dev/stage/prod) | 1, 2 |
-| `EcrEcsConstructs` | Reusable constructs for ECR repo + ECS cluster/service standing up a container image | 1, 2 (image source differs) |
-| `EdgeNetworkingConstructs` | CloudFront, Route53, API Gateway, Cognito construct helpers | 1, 2 |
-| `AppRuntimeScaffold` | TypeScript app source layout, handler patterns | 2 only |
-| `DatabaseComponent` | DB provisioning construct + migration tooling wiring | 2 only |
-| `UpgradeWorkflow` | Nightly dependency upgrade PRs | 1, 2 |
-
-## Workflows Summary
-
-| Workflow | Trigger | Applies to |
-|---|---|---|
-| `pr-check.yml` (synth/diff/lint/test) | PR | 1, 2 |
-| `app-build.yml` | PR / manual | 2 only |
-| `deploy.yml` | Manual dispatch (per environment) | 1, 2 |
-| `upgrade.yml` | Nightly cron | 1, 2 |
-
-## Options Schema (draft)
-
-```typescript
-interface CdkInfraProjectOptions extends CommonCdkOptions {
-  environments: string[]; // e.g. ["dev", "stage", "prod"]
-  ecrEcs?: {
-    enabled?: boolean;
-    externalImageSource?: boolean; // default true for infra-only
-  };
-  edgeResources?: ("cloudfront" | "route53" | "apigateway" | "cognito" | "sqs")[];
-}
-
-interface CdkAppProjectOptions extends CdkInfraProjectOptions {
-  database?: {
-    engine?: "postgres" | "mysql" | "dynamodb";
-    migrationTool?: string;
-  };
-  appEntryPoint?: string; // default handler entry
-}
-
-interface CommonCdkOptions {
-  name: string;
-  cdkVersion?: string;
-  gheTokenSecret?: string; // default: PROJEN_GITHUB_TOKEN
-}
-```
-
-## Open Questions
-- For `CdkAppProject`, is there a single preferred DB engine/migration tool to default to, or should this stay fully pluggable per team?
-- Should `environments` be a fixed convention (dev/stage/prod) baked into the deploy workflow, or arbitrary per project?
-- Does `EcrEcsConstructs` need to support Fargate and EC2 launch types, or is one sufficient for v1?
-- Any need to share constructs between `projen-cdk` and `projen-java`'s `CdkDeployHook` (type 2 in the Java spec), e.g. a common "trigger downstream CDK deploy" contract?
-
-## Out of Scope (v1)
-- Non-API-Gateway compute patterns (e.g., ALB-fronted apps) — revisit if a real use case appears.
-- Automatic production deploys — all deploys remain manual-dispatch per current practice.

package/spec/projen-java-spec.md

@@ -1,96 +0,0 @@
-# projen-java — Project Spec
-
-## Overview
-
-`projen-java` is a projen project-type package (`@cai-projen/projen-java`, following the existing `@cai-projen/projen-general` naming convention) that provides scaffolding for CoxAuto's three Maven-based Java project types. All three share a Maven build skeleton, PR-time build/verify checks, and SonarQube integration; they differ only in publish target and a small set of optional add-ons.
-
-Modeled on the existing `projen-general` pattern (one package, multiple exported project types), rather than one repo per type.
-
-## Project Types
-
-### 1. `JavaLibraryProject`
-- **Purpose:** Reusable Java libraries.
-- **Publish target:** Maven Central.
-- **Requires:** Maven Central credentials/signing secrets (org or repo level), GPG signing config.
-- **Extras:** Code-index generation workflow, publishing the index to the `.cai` directory.
-
-### 2. `JavaServiceProject`
-- **Purpose:** Springboot service applications.
-- **Publish target:** Docker Hub (image build/push). Never published to Maven Central.
-- **Common bundled add-ons (opt-in, on by default):**
-  - Flyway for DB migrations.
-  - CDK deployment hook — a manual-dispatch GitHub Action that triggers/coordinates deployment (assumes a companion `CdkInfraProject`/`CdkAppProject` repo owns the actual infra).
-- **Publish + deploy are both manual-dispatch actions, not on every merge to main.**
-
-### 3. `JavaAppProject`
-- **Purpose:** GUI/TUI/CLI Java applications.
-- **Publish target:** GitHub Packages.
-- **Explicitly excludes:** Maven Central, Docker, CDK deploy hooks.
-
-## Shared Components
-
-These are implemented once as shared projen components/mixins and composed into each type:
-
-| Component | Description | Used by |
-|---|---|---|
-| `MavenBuildComponent` | Base Maven project structure, `pom.xml` management, standard directory layout | 1, 2, 5 |
-| `BuildVerifyWorkflow` | PR-triggered build + test + SonarQube scan. Also runs `npx projen` and `git diff --exit-code` against generated files (`pom.xml`, `.github/workflows/*.yml`) to fail the PR if a hand edit drifted from the projen-managed output | 1, 2, 5 |
-| `CodeIndexWorkflow` | Generates a code index, publishes to `.cai/` | 1 (default on), optional for others |
-| `MavenCentralPublish` | On-demand publish workflow w/ signing + Central credentials | 1 only |
-| `DockerPublish` | Build image, push to Docker Hub, on-demand | 2 only |
-| `GitHubPackagesPublish` | On-demand publish to GH Packages | 5 only |
-| `FlywayMigration` | Adds Flyway config/dependencies + migration directory | 2 (opt-in, default true) |
-| `CdkDeployHook` | Manual-dispatch workflow that invokes a downstream CDK deploy | 2 (opt-in, default true) |
-
-## Workflows Summary
-
-| Workflow | Trigger | Applies to |
-|---|---|---|
-| `build.yml` | PR / manual | All three |
-| `sonar.yml` (or folded into build) | PR / on checkin | All three |
-| `codeindex.yml` | On checkin (or on-demand) | 1 (opt-in for others) |
-| `publish-maven-central.yml` | Manual dispatch | 1 |
-| `publish-docker.yml` | Manual dispatch | 2 |
-| `publish-ghpackages.yml` | Manual dispatch | 5 |
-| `deploy-cdk.yml` | Manual dispatch | 2 (opt-in) |
-| `upgrade.yml` | Nightly cron | All three (dependency upgrades) |
-
-## Options Schema (draft)
-
-```typescript
-interface JavaLibraryProjectOptions extends CommonJavaOptions {
-  mavenCentralOidc?: boolean; // vs. secret-based signing
-  publishCodeIndex?: boolean; // default: true
-}
-
-interface JavaServiceProjectOptions extends CommonJavaOptions {
-  dockerRegistry?: string; // default: Docker Hub
-  useFlyway?: boolean; // default: true
-  cdkDeployHook?: {
-    enabled?: boolean; // default: true
-    targetRepo?: string; // companion CDK infra/app repo
-  };
-}
-
-interface JavaAppProjectOptions extends CommonJavaOptions {
-  ghPackagesRegistry?: string;
-}
-
-interface CommonJavaOptions {
-  name: string;
-  groupId: string;
-  artifactId: string;
-  sonarProjectKey?: string;
-  gheTokenSecret?: string; // default: PROJEN_GITHUB_TOKEN
-}
-```
-
-## Out of Scope (v1)
-- Non-Maven Java build tools (Gradle).
-- Automatic (non-manual) production deploys for type 2.
-- Multi-module Maven project support (evaluate based on early adoption).
-
-## Open Questions
-- Should `CdkDeployHook` in type 2 assume a specific companion repo naming convention, or take an arbitrary target?
-- Does the code-index format/consumer for `.cai` need to be standardized before generalizing beyond type 1?
-- Org-level vs. repo-level secrets for Maven Central signing — confirm current practice before hardcoding assumptions.