@xpertss/projen-types 0.0.3 → 0.0.4

package/API.md

@@ -258,12 +258,16 @@ public readonly workflow: TaskWorkflow;
 
 Per AD-001's dogfood test: the composite action is run **against this repo**, end-to-end, via a local `uses: .` reference - no external harness. Builds `test-dogfood.yml` from an ordered `scenario` of invocation steps (see `ActionDogfoodStep`) followed by a shared cleanup step.
 
+Omitting `options` generates the workflow with a single failing step (see
+`UNCONFIGURED_STEPS`). A *partially* declared dogfood is still a synth
+error: if you wrote a scenario by hand, you can write its cleanup too.
+
 #### Initializers <a name="Initializers" id="@xpertss/projen-types.ActionDogfoodWorkflow.Initializer"></a>
 
 ```typescript
 import { ActionDogfoodWorkflow } from '@xpertss/projen-types'
 
-new ActionDogfoodWorkflow(scope: GitHubProject, options: ActionDogfoodOptions)
+new ActionDogfoodWorkflow(scope: GitHubProject, options?: ActionDogfoodOptions)
 ```
 
 | **Name** | **Type** | **Description** |
@@ -279,7 +283,7 @@ new ActionDogfoodWorkflow(scope: GitHubProject, options: ActionDogfoodOptions)
 
 ---
 
-##### `options`<sup>Required</sup> <a name="options" id="@xpertss/projen-types.ActionDogfoodWorkflow.Initializer.parameter.options"></a>
+##### `options`<sup>Optional</sup> <a name="options" id="@xpertss/projen-types.ActionDogfoodWorkflow.Initializer.parameter.options"></a>
 
 - *Type:* <a href="#@xpertss/projen-types.ActionDogfoodOptions">ActionDogfoodOptions</a>
 
@@ -2664,6 +2668,13 @@ public readonly DEFAULT_TS_JEST_TRANFORM_PATTERN: string;
 
 Manual-dispatch workflow that invokes a downstream CDK deploy in a companion `CdkInfraProject`/`CdkAppProject` repo, using the same `ManualDeployWorkflow` contract those project types use for their own deploys - see the CDK spec's open question about sharing this contract.
 
+With no `targetRepo` the workflow is still generated, but every job's
+only step fails with instructions. Synthesizing is not the place to
+enforce this: it would make the project type unscaffoldable by
+`projen new` (which cannot supply the value), and it is a dispatch-only
+workflow - nobody hits the failure until they actually try to deploy,
+which is exactly when "this repo has no deploy target" needs saying.
+
 #### Initializers <a name="Initializers" id="@xpertss/projen-types.CdkDeployHook.Initializer"></a>
 
 ```typescript
@@ -13099,9 +13110,9 @@ const cdkAppProjectOptions: CdkAppProjectOptions = { ... }
 | <code><a href="#@xpertss/projen-types.CdkAppProjectOptions.property.name">name</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@xpertss/projen-types.CdkAppProjectOptions.property.cdkVersion">cdkVersion</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@xpertss/projen-types.CdkAppProjectOptions.property.gheTokenSecret">gheTokenSecret</a></code> | <code>string</code> | *No description.* |
-| <code><a href="#@xpertss/projen-types.CdkAppProjectOptions.property.environments">environments</a></code> | <code>string \| <a href="#@xpertss/projen-types.EnvironmentOptions">EnvironmentOptions</a>[]</code> | Deploy targets for the manual-dispatch deploy workflow, e.g. ["dev", "stage", "prod"]. |
 | <code><a href="#@xpertss/projen-types.CdkAppProjectOptions.property.ecrEcs">ecrEcs</a></code> | <code><a href="#@xpertss/projen-types.EcrEcsOptions">EcrEcsOptions</a></code> | *No description.* |
 | <code><a href="#@xpertss/projen-types.CdkAppProjectOptions.property.edgeResources">edgeResources</a></code> | <code>string[]</code> | *No description.* |
+| <code><a href="#@xpertss/projen-types.CdkAppProjectOptions.property.environments">environments</a></code> | <code>string \| <a href="#@xpertss/projen-types.EnvironmentOptions">EnvironmentOptions</a>[]</code> | Deploy targets for the manual-dispatch deploy workflow, e.g. ["dev", "stage", "prod"]. No `deploy` workflow is generated when this is empty or omitted. |
 | <code><a href="#@xpertss/projen-types.CdkAppProjectOptions.property.appEntryPoint">appEntryPoint</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@xpertss/projen-types.CdkAppProjectOptions.property.database">database</a></code> | <code><a href="#@xpertss/projen-types.DatabaseOptions">DatabaseOptions</a></code> | *No description.* |
 
@@ -13139,35 +13150,42 @@ public readonly gheTokenSecret: string;
 
 ---
 
-##### `environments`<sup>Required</sup> <a name="environments" id="@xpertss/projen-types.CdkAppProjectOptions.property.environments"></a>
+##### `ecrEcs`<sup>Optional</sup> <a name="ecrEcs" id="@xpertss/projen-types.CdkAppProjectOptions.property.ecrEcs"></a>
 
 ```typescript
-public readonly environments: (string | EnvironmentOptions)[];
+public readonly ecrEcs: EcrEcsOptions;
 ```
 
-- *Type:* string | <a href="#@xpertss/projen-types.EnvironmentOptions">EnvironmentOptions</a>[]
-
-Deploy targets for the manual-dispatch deploy workflow, e.g. ["dev", "stage", "prod"].
+- *Type:* <a href="#@xpertss/projen-types.EcrEcsOptions">EcrEcsOptions</a>
 
 ---
 
-##### `ecrEcs`<sup>Optional</sup> <a name="ecrEcs" id="@xpertss/projen-types.CdkAppProjectOptions.property.ecrEcs"></a>
+##### `edgeResources`<sup>Optional</sup> <a name="edgeResources" id="@xpertss/projen-types.CdkAppProjectOptions.property.edgeResources"></a>
 
 ```typescript
-public readonly ecrEcs: EcrEcsOptions;
+public readonly edgeResources: string[];
 ```
 
-- *Type:* <a href="#@xpertss/projen-types.EcrEcsOptions">EcrEcsOptions</a>
+- *Type:* string[]
 
 ---
 
-##### `edgeResources`<sup>Optional</sup> <a name="edgeResources" id="@xpertss/projen-types.CdkAppProjectOptions.property.edgeResources"></a>
+##### `environments`<sup>Optional</sup> <a name="environments" id="@xpertss/projen-types.CdkAppProjectOptions.property.environments"></a>
 
 ```typescript
-public readonly edgeResources: string[];
+public readonly environments: (string | EnvironmentOptions)[];
 ```
 
-- *Type:* string[]
+- *Type:* string | <a href="#@xpertss/projen-types.EnvironmentOptions">EnvironmentOptions</a>[]
+- *Default:* no deploy workflow
+
+Deploy targets for the manual-dispatch deploy workflow, e.g. ["dev", "stage", "prod"]. No `deploy` workflow is generated when this is empty or omitted.
+
+Optional rather than required so that `projen new --from` can scaffold
+the repo: its union type (`string | EnvironmentOptions`) is not
+"JSON-like", so projen's CLI cannot render a value for it into the
+initial `.projenrc.ts` - and a *required* option it cannot render leaves
+behind a projenrc that does not type-check.
 
 ---
 
@@ -13206,22 +13224,10 @@ const cdkDeployHookOptions: CdkDeployHookOptions = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
-| <code><a href="#@xpertss/projen-types.CdkDeployHookOptions.property.enabled">enabled</a></code> | <code>boolean</code> | *No description.* |
 | <code><a href="#@xpertss/projen-types.CdkDeployHookOptions.property.targetRepo">targetRepo</a></code> | <code>string</code> | The companion CDK infra/app repo (owner/repo) that owns the actual infrastructure. |
 
 ---
 
-##### `enabled`<sup>Optional</sup> <a name="enabled" id="@xpertss/projen-types.CdkDeployHookOptions.property.enabled"></a>
-
-```typescript
-public readonly enabled: boolean;
-```
-
-- *Type:* boolean
-- *Default:* true
-
----
-
 ##### `targetRepo`<sup>Optional</sup> <a name="targetRepo" id="@xpertss/projen-types.CdkDeployHookOptions.property.targetRepo"></a>
 
 ```typescript
@@ -13229,6 +13235,7 @@ public readonly targetRepo: string;
 ```
 
 - *Type:* string
+- *Default:* the workflow is still generated, but its only step fails with instructions (see `CdkDeployHook`)
 
 The companion CDK infra/app repo (owner/repo) that owns the actual infrastructure.
 
@@ -13251,9 +13258,9 @@ const cdkInfraProjectOptions: CdkInfraProjectOptions = { ... }
 | <code><a href="#@xpertss/projen-types.CdkInfraProjectOptions.property.name">name</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@xpertss/projen-types.CdkInfraProjectOptions.property.cdkVersion">cdkVersion</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@xpertss/projen-types.CdkInfraProjectOptions.property.gheTokenSecret">gheTokenSecret</a></code> | <code>string</code> | *No description.* |
-| <code><a href="#@xpertss/projen-types.CdkInfraProjectOptions.property.environments">environments</a></code> | <code>string \| <a href="#@xpertss/projen-types.EnvironmentOptions">EnvironmentOptions</a>[]</code> | Deploy targets for the manual-dispatch deploy workflow, e.g. ["dev", "stage", "prod"]. |
 | <code><a href="#@xpertss/projen-types.CdkInfraProjectOptions.property.ecrEcs">ecrEcs</a></code> | <code><a href="#@xpertss/projen-types.EcrEcsOptions">EcrEcsOptions</a></code> | *No description.* |
 | <code><a href="#@xpertss/projen-types.CdkInfraProjectOptions.property.edgeResources">edgeResources</a></code> | <code>string[]</code> | *No description.* |
+| <code><a href="#@xpertss/projen-types.CdkInfraProjectOptions.property.environments">environments</a></code> | <code>string \| <a href="#@xpertss/projen-types.EnvironmentOptions">EnvironmentOptions</a>[]</code> | Deploy targets for the manual-dispatch deploy workflow, e.g. ["dev", "stage", "prod"]. No `deploy` workflow is generated when this is empty or omitted. |
 
 ---
 
@@ -13289,35 +13296,42 @@ public readonly gheTokenSecret: string;
 
 ---
 
-##### `environments`<sup>Required</sup> <a name="environments" id="@xpertss/projen-types.CdkInfraProjectOptions.property.environments"></a>
+##### `ecrEcs`<sup>Optional</sup> <a name="ecrEcs" id="@xpertss/projen-types.CdkInfraProjectOptions.property.ecrEcs"></a>
 
 ```typescript
-public readonly environments: (string | EnvironmentOptions)[];
+public readonly ecrEcs: EcrEcsOptions;
 ```
 
-- *Type:* string | <a href="#@xpertss/projen-types.EnvironmentOptions">EnvironmentOptions</a>[]
-
-Deploy targets for the manual-dispatch deploy workflow, e.g. ["dev", "stage", "prod"].
+- *Type:* <a href="#@xpertss/projen-types.EcrEcsOptions">EcrEcsOptions</a>
 
 ---
 
-##### `ecrEcs`<sup>Optional</sup> <a name="ecrEcs" id="@xpertss/projen-types.CdkInfraProjectOptions.property.ecrEcs"></a>
+##### `edgeResources`<sup>Optional</sup> <a name="edgeResources" id="@xpertss/projen-types.CdkInfraProjectOptions.property.edgeResources"></a>
 
 ```typescript
-public readonly ecrEcs: EcrEcsOptions;
+public readonly edgeResources: string[];
 ```
 
-- *Type:* <a href="#@xpertss/projen-types.EcrEcsOptions">EcrEcsOptions</a>
+- *Type:* string[]
 
 ---
 
-##### `edgeResources`<sup>Optional</sup> <a name="edgeResources" id="@xpertss/projen-types.CdkInfraProjectOptions.property.edgeResources"></a>
+##### `environments`<sup>Optional</sup> <a name="environments" id="@xpertss/projen-types.CdkInfraProjectOptions.property.environments"></a>
 
 ```typescript
-public readonly edgeResources: string[];
+public readonly environments: (string | EnvironmentOptions)[];
 ```
 
-- *Type:* string[]
+- *Type:* string | <a href="#@xpertss/projen-types.EnvironmentOptions">EnvironmentOptions</a>[]
+- *Default:* no deploy workflow
+
+Deploy targets for the manual-dispatch deploy workflow, e.g. ["dev", "stage", "prod"]. No `deploy` workflow is generated when this is empty or omitted.
+
+Optional rather than required so that `projen new --from` can scaffold
+the repo: its union type (`string | EnvironmentOptions`) is not
+"JSON-like", so projen's CLI cannot render a value for it into the
+initial `.projenrc.ts` - and a *required* option it cannot render leaves
+behind a projenrc that does not type-check.
 
 ---
 
@@ -13751,9 +13765,9 @@ const gitHubActionProjectOptions: GitHubActionProjectOptions = { ... }
 | <code><a href="#@xpertss/projen-types.GitHubActionProjectOptions.property.stale">stale</a></code> | <code>boolean</code> | Auto-close of stale issues and pull request. |
 | <code><a href="#@xpertss/projen-types.GitHubActionProjectOptions.property.staleOptions">staleOptions</a></code> | <code>projen.github.StaleOptions</code> | Auto-close stale issues and pull requests. |
 | <code><a href="#@xpertss/projen-types.GitHubActionProjectOptions.property.vscode">vscode</a></code> | <code>boolean</code> | Enable VSCode integration. |
-| <code><a href="#@xpertss/projen-types.GitHubActionProjectOptions.property.dogfood">dogfood</a></code> | <code><a href="#@xpertss/projen-types.ActionDogfoodOptions">ActionDogfoodOptions</a></code> | The dogfood scenario (AD-001). |
 | <code><a href="#@xpertss/projen-types.GitHubActionProjectOptions.property.sonarHostUrl">sonarHostUrl</a></code> | <code>string</code> | URL of the org's self-hosted SonarQube instance. |
 | <code><a href="#@xpertss/projen-types.GitHubActionProjectOptions.property.description">description</a></code> | <code>string</code> | One-line description of the action. |
+| <code><a href="#@xpertss/projen-types.GitHubActionProjectOptions.property.dogfood">dogfood</a></code> | <code><a href="#@xpertss/projen-types.ActionDogfoodOptions">ActionDogfoodOptions</a></code> | The dogfood scenario (AD-001). |
 | <code><a href="#@xpertss/projen-types.GitHubActionProjectOptions.property.gheTokenSecret">gheTokenSecret</a></code> | <code>string</code> | Name of the GitHub Actions secret holding the PAT used for projen-automation PR comments (F003/F009) and, when the action has a `token` input, the dogfood's invocation of it. |
 | <code><a href="#@xpertss/projen-types.GitHubActionProjectOptions.property.license">license</a></code> | <code>string</code> | SPDX identifier for the generated `LICENSE`. |
 | <code><a href="#@xpertss/projen-types.GitHubActionProjectOptions.property.sonarPullRequestGate">sonarPullRequestGate</a></code> | <code>boolean</code> | Whether `sonar.yml` also runs on `pull_request` as a pass/fail gate. |
@@ -14129,23 +14143,6 @@ Enabled by default for root projects. Disabled for non-root projects.
 
 ---
 
-##### `dogfood`<sup>Required</sup> <a name="dogfood" id="@xpertss/projen-types.GitHubActionProjectOptions.property.dogfood"></a>
-
-```typescript
-public readonly dogfood: ActionDogfoodOptions;
-```
-
-- *Type:* <a href="#@xpertss/projen-types.ActionDogfoodOptions">ActionDogfoodOptions</a>
-
-The dogfood scenario (AD-001).
-
-What fixture state, what to assert, and
-how to clean up are specified by the action's own F### spec - the
-highest-risk behavior of that action. Required: a default no-op
-dogfood would silently hollow out a load-bearing AD-001 workflow.
-
----
-
 ##### `sonarHostUrl`<sup>Required</sup> <a name="sonarHostUrl" id="@xpertss/projen-types.GitHubActionProjectOptions.property.sonarHostUrl"></a>
 
 ```typescript
@@ -14177,6 +14174,30 @@ template and recorded in the private `package.json`.
 
 ---
 
+##### `dogfood`<sup>Optional</sup> <a name="dogfood" id="@xpertss/projen-types.GitHubActionProjectOptions.property.dogfood"></a>
+
+```typescript
+public readonly dogfood: ActionDogfoodOptions;
+```
+
+- *Type:* <a href="#@xpertss/projen-types.ActionDogfoodOptions">ActionDogfoodOptions</a>
+- *Default:* `test-dogfood.yml` runs one failing step that tells you to declare a scenario
+
+The dogfood scenario (AD-001).
+
+What fixture state, what to assert, and
+how to clean up are specified by the action's own F### spec - the
+highest-risk behavior of that action.
+
+Its type is a struct, which projen's CLI cannot render into a projenrc,
+so it can only be written by hand - it is therefore optional, because a
+*required* option `projen new` cannot supply would make this project
+type impossible to scaffold. AD-001's "never a silent no-op dogfood"
+rule is enforced instead by the workflow it generates in that case: a
+single step that fails on every PR until a scenario is declared.
+
+---
+
 ##### `gheTokenSecret`<sup>Optional</sup> <a name="gheTokenSecret" id="@xpertss/projen-types.GitHubActionProjectOptions.property.gheTokenSecret"></a>
 
 ```typescript
@@ -14580,7 +14601,8 @@ const javaServiceProjectOptions: JavaServiceProjectOptions = { ... }
 | <code><a href="#@xpertss/projen-types.JavaServiceProjectOptions.property.gheTokenSecret">gheTokenSecret</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@xpertss/projen-types.JavaServiceProjectOptions.property.sonarProjectKey">sonarProjectKey</a></code> | <code>string</code> | SonarQube project key. |
 | <code><a href="#@xpertss/projen-types.JavaServiceProjectOptions.property.version">version</a></code> | <code>string</code> | *No description.* |
-| <code><a href="#@xpertss/projen-types.JavaServiceProjectOptions.property.cdkDeployHook">cdkDeployHook</a></code> | <code><a href="#@xpertss/projen-types.CdkDeployHookOptions">CdkDeployHookOptions</a></code> | *No description.* |
+| <code><a href="#@xpertss/projen-types.JavaServiceProjectOptions.property.cdkDeployHook">cdkDeployHook</a></code> | <code>boolean</code> | Whether to generate the `deploy-cdk` workflow at all. |
+| <code><a href="#@xpertss/projen-types.JavaServiceProjectOptions.property.cdkDeployTargetRepo">cdkDeployTargetRepo</a></code> | <code>string</code> | The companion CDK infra/app repo (`owner/repo`) whose `deploy.yml` the `deploy-cdk` workflow dispatches. |
 | <code><a href="#@xpertss/projen-types.JavaServiceProjectOptions.property.dockerRegistry">dockerRegistry</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@xpertss/projen-types.JavaServiceProjectOptions.property.environments">environments</a></code> | <code>string \| <a href="#@xpertss/projen-types.EnvironmentOptions">EnvironmentOptions</a>[]</code> | Deploy targets to offer on the `CdkDeployHook`'s manual-dispatch workflow, when the hook is enabled. |
 | <code><a href="#@xpertss/projen-types.JavaServiceProjectOptions.property.useFlyway">useFlyway</a></code> | <code>boolean</code> | *No description.* |
@@ -14656,11 +14678,29 @@ public readonly version: string;
 ##### `cdkDeployHook`<sup>Optional</sup> <a name="cdkDeployHook" id="@xpertss/projen-types.JavaServiceProjectOptions.property.cdkDeployHook"></a>
 
 ```typescript
-public readonly cdkDeployHook: CdkDeployHookOptions;
+public readonly cdkDeployHook: boolean;
 ```
 
-- *Type:* <a href="#@xpertss/projen-types.CdkDeployHookOptions">CdkDeployHookOptions</a>
-- *Default:* { enabled: true }
+- *Type:* boolean
+- *Default:* true
+
+Whether to generate the `deploy-cdk` workflow at all.
+
+---
+
+##### `cdkDeployTargetRepo`<sup>Optional</sup> <a name="cdkDeployTargetRepo" id="@xpertss/projen-types.JavaServiceProjectOptions.property.cdkDeployTargetRepo"></a>
+
+```typescript
+public readonly cdkDeployTargetRepo: string;
+```
+
+- *Type:* string
+- *Default:* `deploy-cdk.yml` is generated with a single failing step that tells you to set this
+
+The companion CDK infra/app repo (`owner/repo`) whose `deploy.yml` the `deploy-cdk` workflow dispatches.
+
+A plain string rather than a nested struct so that
+`projen new --from
 
 ---
 

package/README.md

@@ -2,7 +2,7 @@
 
 Projen project types for CDK/TypeScript and Java/Maven projects.
 
-Instead of hand-maintaining `pom.xml`, `cdk.json`, and GitHub workflows, you declare a project type in a plain-JavaScript `.projenrc.js` file and let [projen](https://github.com/projen/projen) generate (and keep up to date) the whole scaffold: build files, source skeletons, CI workflows, and deploy pipelines.
+Instead of hand-maintaining `pom.xml`, `cdk.json`, and GitHub workflows, you declare a project type in a `.projenrc.ts` file and let [projen](https://github.com/projen/projen) generate (and keep up to date) the whole scaffold: build files, source skeletons, CI workflows, and deploy pipelines.
 
 ## Project types at a glance
 
@@ -19,27 +19,45 @@ Two foundation classes are also exported for advanced use: `CdkTypescriptProject
 
 All project types:
 
-- run a **drift check** in PR builds - a job that re-runs projen and fails if generated files were hand-edited. Edit `.projenrc.js`, then run `npx projen`; never edit generated files directly.
+- run a **drift check** in PR builds - a job that re-runs projen and fails if generated files were hand-edited. Edit `.projenrc.ts`, then run `npx projen`; never edit generated files directly.
 - use the GitHub secret `PROJEN_GITHUB_TOKEN` (a fine-grained PAT) for projen's automation. Override with `gheTokenSecret`.
 - make all publishing/deploying **manual** (workflow_dispatch) rather than on every merge.
 
 ## Getting started
 
-Create a new git repository and install the dependencies:
+Scaffold the repo with projen's own bootstrap, pointed at this package:
 
 ```bash
 mkdir my-project && cd my-project
 git init
-npm install -D projen constructs @xpertss/projen-types
+npx projen new --from @xpertss/projen-types cdk_infra --name my-project
 ```
 
-Write a `.projenrc.js` (see examples below), then bootstrap the project by running it directly - `npx projen` alone can't do this on a brand-new repo, since it only re-runs a `default` task that doesn't exist yet:
+That writes a starter `.projenrc.ts`, synthesizes the whole scaffold and
+installs dependencies. The type names `projen new` accepts are `cdk_infra`,
+`cdk_app`, `java_library`, `java_service`, `java_app` and
+`git_hub_action`; pass a bogus one to have it list them. Required options
+become flags: `--name` for every type, plus `--group-id`/`--artifact-id`
+(Java) and `--sonar-host-url` (`git_hub_action`). Any other plainly-typed
+option can be passed the same way - `--cdk-deploy-target-repo owner/repo`,
+`--docker-registry ghcr.io`, `--no-use-flyway`, and so on.
+
+Commit the result. From then on, every change to the scaffold goes through
+`.projenrc.ts` followed by `npx projen`:
 
 ```bash
-node .projenrc.js
+npx projen
 ```
 
-Commit the result. From then on, every change to the scaffold goes through `.projenrc.js` followed by plain `npx projen`.
+Every type scaffolds from that one command; no option is *required* that
+`projen new` cannot pass. The structured options - `environments` and
+`GitHubActionProject`'s `dogfood` - are ones projen's CLI cannot render
+into a projenrc, so they are added afterwards by editing `.projenrc.ts` and
+re-running `npx projen`. Leaving `environments` out simply generates no
+deploy workflow; leaving `dogfood` out (or a service's
+`cdkDeployTargetRepo`) still generates the workflow, with one step that
+fails and tells you what to add - a gate this package considers load-bearing
+is allowed to be missing loudly, never silently.
 
 The `name` option must match the `name` field in the project's `package.json` (for the CDK types) or the project name used by projen's `java.JavaProject` (for the Java types).
 
@@ -49,9 +67,9 @@ The `name` option must match the `name` field in the project's `package.json` (f
 
 Pure infrastructure stacks with optional ECR/ECS and edge-networking constructs.
 
-```javascript
-// .projenrc.js
-const { CdkInfraProject } = require('@xpertss/projen-types');
+```typescript
+// .projenrc.ts
+import { CdkInfraProject } from '@xpertss/projen-types';
 
 const project = new CdkInfraProject({
   name: 'media-edge-infra',
@@ -80,9 +98,9 @@ You get:
 
 `CdkInfraProject` plus application source, a database construct, and an app-level build workflow.
 
-```javascript
-// .projenrc.js
-const { CdkAppProject } = require('@xpertss/projen-types');
+```typescript
+// .projenrc.ts
+import { CdkAppProject } from '@xpertss/projen-types';
 
 const project = new CdkAppProject({
   name: 'video-api',
@@ -106,9 +124,9 @@ Everything from `CdkInfraProject`, plus:
 
 A reusable Java library published to Maven Central.
 
-```javascript
-// .projenrc.js
-const { JavaLibraryProject } = require('@xpertss/projen-types');
+```typescript
+// .projenrc.ts
+import { JavaLibraryProject } from '@xpertss/projen-types';
 
 const project = new JavaLibraryProject({
   name: 'common-utils',
@@ -134,16 +152,16 @@ You get:
 
 A Spring Boot service that publishes a Docker image and can trigger deploys in a companion CDK repo.
 
-```javascript
-// .projenrc.js
-const { JavaServiceProject } = require('@xpertss/projen-types');
+```typescript
+// .projenrc.ts
+import { JavaServiceProject } from '@xpertss/projen-types';
 
 const project = new JavaServiceProject({
   name: 'stream-processor',
   groupId: 'org.xpertss',
   artifactId: 'stream-processor',
   dockerRegistry: 'docker.io/xpertss',
-  cdkDeployHook: { targetRepo: 'xpertss/stream-infra' },
+  cdkDeployTargetRepo: 'xpertss/stream-infra',
   environments: ['dev', { name: 'prod', requiresApproval: true }],
 });
 
@@ -155,15 +173,15 @@ You get (everything from `JavaMavenProject` - `pom.xml`, `build` + drift check,
 - `spring-boot-starter-web` added to the pom.
 - `.github/workflows/publish-docker.yml` - manual dispatch: `mvn -B package && docker build -t <registry>/<name>:<sha>`, logged in with the `DOCKER_USERNAME` / `DOCKER_PASSWORD` secrets. `dockerRegistry` defaults to `docker.io`.
 - Flyway wiring when `useFlyway` (default `true`): `flyway-maven-plugin` ^10 + `flyway-core` ^10 in the pom, and `src/main/resources/db/migration/V1__init.sql`.
-- `.github/workflows/deploy-cdk.yml` (the `CdkDeployHook`, enabled by default) - manual dispatch with an environment selector; each job sends a `workflow_dispatch` to `deploy.yml` in the companion `targetRepo` (a `CdkInfraProject`/`CdkAppProject` repo). `targetRepo` is required when the hook is enabled; disable it with `cdkDeployHook: { enabled: false }`. `environments` defaults to `['prod']`.
+- `.github/workflows/deploy-cdk.yml` (the `CdkDeployHook`, generated by default) - manual dispatch with an environment selector; each job sends a `workflow_dispatch` to `deploy.yml` in the companion `cdkDeployTargetRepo` (a `CdkInfraProject`/`CdkAppProject` repo). With no `cdkDeployTargetRepo` set, the workflow is still generated but each job's only step fails with instructions - it is dispatch-only, so that lands on whoever tries to deploy rather than on every PR. Turn the workflow off entirely with `cdkDeployHook: false`. `environments` defaults to `['prod']`.
 
 ### JavaAppProject
 
 A GUI/TUI/CLI Java application published to GitHub Packages only - no Maven Central, no Docker, no CDK deploy hook.
 
-```javascript
-// .projenrc.js
-const { JavaAppProject } = require('@xpertss/projen-types');
+```typescript
+// .projenrc.ts
+import { JavaAppProject } from '@xpertss/projen-types';
 
 const project = new JavaAppProject({
   name: 'studio-cli',
@@ -181,9 +199,9 @@ You get everything from `JavaMavenProject`, plus `.github/workflows/publish-ghpa
 
 A reusable GitHub Action or Workflow. This example scaffolds an action that stages a folder and, only if it changed, commits and pushes it.
 
-```javascript
-// .projenrc.js
-const { GitHubActionProject } = require('@xpertss/projen-types');
+```typescript
+// .projenrc.ts
+import { GitHubActionProject } from '@xpertss/projen-types';
 
 const project = new GitHubActionProject({
   name: 'auto-commit',
@@ -235,13 +253,13 @@ You get:
 
 - `action.yml` and `auto-commit.sh` are hand-written - this type only lints their content via `build.yml`'s shellcheck/yamllint/actionlint checks.
 - `.github/workflows/build.yml` - lint gate: `apt`-installed shellcheck/yamllint plus a pinned, SHA-256-verified `actionlint` release binary. Gates `main` alongside `sonar.yml`.
-- `.github/workflows/test-dogfood.yml` - runs the `dogfood.scenario` steps above against this repo's own `action.yml` (via `uses: .`), then the shared `cleanup`, on `workflow_dispatch`, every `pull_request`, and nightly.
+- `.github/workflows/test-dogfood.yml` - runs the `dogfood.scenario` steps above against this repo's own `action.yml` (via `uses: .`), then the shared `cleanup`, on `workflow_dispatch`, every `pull_request`, and nightly. Omit `dogfood` and the workflow still exists, with one step that fails on every PR until you declare a scenario - AD-001 allows a dogfood to be missing loudly, never silently. A *partial* `dogfood` (a scenario with no cleanup) is a synth error.
 - `.github/workflows/sonar.yml` - self-hosted SonarQube via the Scanner CLI, scanning `action.yml`/`.github/workflows/**`/`**/*.sh` explicitly.
 - `.github/workflows/release.yml` - `feat:`/`fix:` commits on `main` bump the version, tag `vX.Y.Z`, and create a GitHub Release.
 - `.github/workflows/projen-drift-check.yml`, `workflow-change-notice.yml`, `actions-allowlist-guard.yml` - drift detection, a change notice, and an action allow-list guard, always included.
 - `package.json` (**private**, version source only), `.yamllint`, `LICENSE` (MIT by default), and a `README.md` template - all regenerated by `npx projen`.
 
-Needs the same two secrets as everything else in this package: `PROJEN_GITHUB_TOKEN` (used for automated PR comments) and `SONAR_TOKEN` (the Sonar scan). Onboard a brand-new action repo following [Getting started](#getting-started), write the `.projenrc.js` above, then hand-write `action.yml`/`auto-commit.sh`/`test/fixtures/`.
+Needs the same two secrets as everything else in this package: `PROJEN_GITHUB_TOKEN` (used for automated PR comments) and `SONAR_TOKEN` (the Sonar scan). Onboard a brand-new action repo following [Getting started](#getting-started), write the `.projenrc.ts` above, then hand-write `action.yml`/`auto-commit.sh`/`test/fixtures/`.
 
 ## Common options
 
@@ -253,7 +271,7 @@ CDK project types (`CdkInfraProjectOptions` / `CdkAppProjectOptions`):
 | `cdkVersion` | `2.189.1` | AWS CDK version |
 | `gheTokenSecret` | `PROJEN_GITHUB_TOKEN` | GitHub secret holding projen's PAT |
 | `slackWebhookSecret` | - | GitHub secret with a Slack webhook URL for deploy notifications |
-| `environments` | - (required) | Deploy targets for the `deploy` workflow; strings or `EnvironmentOptions` |
+| `environments` | - (no `deploy` workflow) | Deploy targets for the `deploy` workflow; strings or `EnvironmentOptions` |
 | `ecrEcs` | - | `EcrEcsOptions` - `enabled`, `externalImageSource` (default `true`) |
 | `edgeResources` | - | Subset of `cloudfront`, `route53`, `apigateway`, `cognito`, `sqs` |
 | `database` | - (app only) | `DatabaseOptions` - `engine` (`postgres`/`mysql`/`dynamodb`, default `postgres`), `migrationTool` |
@@ -269,6 +287,10 @@ Java project types (`JavaLibraryProjectOptions` / `JavaServiceProjectOptions` /
 | `version` | `0.1.0` | Maven version |
 | `sonarProjectKey` | - | SonarQube project key; the sonar step is skipped when unset |
 | `gheTokenSecret` | `PROJEN_GITHUB_TOKEN` | GitHub secret holding projen's PAT |
+| `cdkDeployTargetRepo` | - (service only; `deploy-cdk.yml` fails until set) | Companion CDK repo (`owner/repo`) whose `deploy.yml` the deploy hook dispatches |
+| `cdkDeployHook` | `true` (service only) | Whether to generate `deploy-cdk.yml` at all |
+| `dockerRegistry` | `docker.io` (service only) | Registry the Docker image is pushed to |
+| `useFlyway` | `true` (service only) | Flyway plugin/dependency + `V1__init.sql` |
 
 `EnvironmentOptions` for deploy targets:
 
@@ -292,7 +314,7 @@ Plain strings (`'dev'`) are shorthand for `{ name: 'dev' }`.
 | `sonarHostUrl` | - (required) | URL of your self-hosted SonarQube instance; must be reachable from github.com-hosted runners |
 | `sonarTokenSecret` | `SONAR_TOKEN` | GitHub secret holding the Sonar token |
 | `sonarPullRequestGate` | `true` | Whether `sonar.yml` also runs on `pull_request` as a pass/fail gate |
-| `dogfood` | - (required) | `ActionDogfoodOptions` - the scenario that exercises the action end-to-end via `uses: .` |
+| `dogfood` | - (a `test-dogfood.yml` that fails until you declare one) | `ActionDogfoodOptions` - the scenario that exercises the action end-to-end via `uses: .` |
 | `license` | `MIT` | SPDX identifier for the generated `LICENSE` |
 | `gheTokenSecret` | `PROJEN_GITHUB_TOKEN` | GitHub secret holding projen's PAT |
 
@@ -347,9 +369,9 @@ The project types are composed from smaller components you can also attach to yo
 
 Example - adding a Docker publish to a plain projen `JavaProject`:
 
-```javascript
-const { java } = require('projen');
-const { DockerPublish } = require('@xpertss/projen-types');
+```typescript
+import { java } from 'projen';
+import { DockerPublish } from '@xpertss/projen-types';
 
 const project = new java.JavaProject({
   name: 'my-service',

package/lib/actions/action-build-workflow.js

@@ -19,7 +19,7 @@ const ACTIONLINT_SHA256 = '8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc
  * the release build job, so the lint commands exist in exactly one place.
  */
 class ActionBuildWorkflow extends projen_1.Component {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@xpertss/projen-types.ActionBuildWorkflow", version: "0.0.3" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@xpertss/projen-types.ActionBuildWorkflow", version: "0.0.4" };
     task;
     workflow;
     constructor(scope) {

package/lib/actions/action-dogfood-workflow.d.ts

@@ -40,8 +40,12 @@ export interface ActionDogfoodOptions {
  * repo**, end-to-end, via a local `uses: .` reference - no external harness.
  * Builds `test-dogfood.yml` from an ordered `scenario` of invocation steps
  * (see `ActionDogfoodStep`) followed by a shared cleanup step.
+ *
+ * Omitting `options` generates the workflow with a single failing step (see
+ * `UNCONFIGURED_STEPS`). A *partially* declared dogfood is still a synth
+ * error: if you wrote a scenario by hand, you can write its cleanup too.
  */
 export declare class ActionDogfoodWorkflow extends Component {
     readonly workflow: github.GithubWorkflow;
-    constructor(scope: github.GitHubProject, options: ActionDogfoodOptions);
+    constructor(scope: github.GitHubProject, options?: ActionDogfoodOptions);
 }