@cbnventures/nova 0.34.1 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (158) hide show
  1. package/bin/nova.mjs +17 -0
  2. package/build/package.json +3 -2
  3. package/build/scaffold-versions.json +16 -6
  4. package/build/src/cli/generate/github/workflows-blueprint-validate.d.ts +2 -2
  5. package/build/src/cli/generate/github/workflows-blueprint-validate.d.ts.map +1 -1
  6. package/build/src/cli/generate/github/workflows-blueprint-validate.js +116 -3
  7. package/build/src/cli/generate/github/workflows-blueprint-validate.js.map +1 -1
  8. package/build/src/cli/generate/github/workflows-blueprint.d.ts +11 -5
  9. package/build/src/cli/generate/github/workflows-blueprint.d.ts.map +1 -1
  10. package/build/src/cli/generate/github/workflows-blueprint.js +411 -35
  11. package/build/src/cli/generate/github/workflows-blueprint.js.map +1 -1
  12. package/build/src/cli/generate/must-haves/agent-conventions.d.ts.map +1 -1
  13. package/build/src/cli/generate/must-haves/agent-conventions.js +3 -0
  14. package/build/src/cli/generate/must-haves/agent-conventions.js.map +1 -1
  15. package/build/src/cli/generate/must-haves/dotenv.d.ts.map +1 -1
  16. package/build/src/cli/generate/must-haves/dotenv.js +1 -0
  17. package/build/src/cli/generate/must-haves/dotenv.js.map +1 -1
  18. package/build/src/cli/scaffold/app/vite.js +1 -1
  19. package/build/src/cli/scaffold/app/vite.js.map +1 -1
  20. package/build/src/cli/utility/changelog.d.ts.map +1 -1
  21. package/build/src/cli/utility/changelog.js +119 -67
  22. package/build/src/cli/utility/changelog.js.map +1 -1
  23. package/build/src/cli/utility/configure.d.ts.map +1 -1
  24. package/build/src/cli/utility/configure.js +126 -1
  25. package/build/src/cli/utility/configure.js.map +1 -1
  26. package/build/src/lib/corepack.d.ts +2 -2
  27. package/build/src/lib/corepack.d.ts.map +1 -1
  28. package/build/src/lib/corepack.js +16 -6
  29. package/build/src/lib/corepack.js.map +1 -1
  30. package/build/src/lib/docker-packaging.d.ts.map +1 -1
  31. package/build/src/lib/docker-packaging.js +5 -4
  32. package/build/src/lib/docker-packaging.js.map +1 -1
  33. package/build/src/lib/dotenv.d.ts.map +1 -1
  34. package/build/src/lib/dotenv.js +17 -8
  35. package/build/src/lib/dotenv.js.map +1 -1
  36. package/build/src/lib/env-managed-set.d.ts.map +1 -1
  37. package/build/src/lib/env-managed-set.js +55 -11
  38. package/build/src/lib/env-managed-set.js.map +1 -1
  39. package/build/src/lib/env-namespace.d.ts.map +1 -1
  40. package/build/src/lib/env-namespace.js +1 -0
  41. package/build/src/lib/env-namespace.js.map +1 -1
  42. package/build/src/lib/env-profiles.d.ts +3 -0
  43. package/build/src/lib/env-profiles.d.ts.map +1 -0
  44. package/build/src/lib/env-profiles.js +70 -0
  45. package/build/src/lib/env-profiles.js.map +1 -0
  46. package/build/src/lib/env-status.d.ts.map +1 -1
  47. package/build/src/lib/env-status.js +23 -2
  48. package/build/src/lib/env-status.js.map +1 -1
  49. package/build/src/lib/item.d.ts.map +1 -1
  50. package/build/src/lib/item.js +20 -3
  51. package/build/src/lib/item.js.map +1 -1
  52. package/build/src/lib/nova-config.d.ts.map +1 -1
  53. package/build/src/lib/nova-config.js +31 -0
  54. package/build/src/lib/nova-config.js.map +1 -1
  55. package/build/src/lib/regex.d.ts +7 -0
  56. package/build/src/lib/regex.d.ts.map +1 -1
  57. package/build/src/lib/regex.js +7 -0
  58. package/build/src/lib/regex.js.map +1 -1
  59. package/build/src/lib/run-scripts.d.ts.map +1 -1
  60. package/build/src/lib/run-scripts.js +24 -0
  61. package/build/src/lib/run-scripts.js.map +1 -1
  62. package/build/src/lib/scaffold.d.ts.map +1 -1
  63. package/build/src/lib/scaffold.js +7 -0
  64. package/build/src/lib/scaffold.js.map +1 -1
  65. package/build/src/lib/workflow-templates.js +4 -4
  66. package/build/src/lib/workflow-templates.js.map +1 -1
  67. package/build/src/types/cli/generate/github/workflows-blueprint-validate.d.ts +42 -4
  68. package/build/src/types/cli/generate/github/workflows-blueprint.d.ts +193 -17
  69. package/build/src/types/cli/utility/changelog.d.ts +49 -6
  70. package/build/src/types/cli/utility/configure.d.ts +52 -0
  71. package/build/src/types/lib/corepack.d.ts +13 -0
  72. package/build/src/types/lib/docker-packaging.d.ts +1 -0
  73. package/build/src/types/lib/dotenv.d.ts +10 -3
  74. package/build/src/types/lib/env-managed-set.d.ts +15 -0
  75. package/build/src/types/lib/env-namespace.d.ts +5 -0
  76. package/build/src/types/lib/env-profiles.d.ts +67 -0
  77. package/build/src/types/lib/env-status.d.ts +9 -0
  78. package/build/src/types/lib/item.d.ts +20 -3
  79. package/build/src/types/lib/nova-config.d.ts +14 -0
  80. package/build/src/types/lib/run-scripts.d.ts +16 -0
  81. package/build/src/types/lib/scaffold.d.ts +8 -0
  82. package/build/src/types/shared.d.ts +47 -0
  83. package/build/src/types/tests/cli/generate/github/workflows-blueprint-publish-parity.test.d.ts +20 -0
  84. package/build/src/types/tests/cli/generate/github/workflows-blueprint-validate.test.d.ts +22 -0
  85. package/build/src/types/tests/cli/generate/github/workflows-blueprint.test.d.ts +16 -0
  86. package/build/src/types/tests/cli/generate/must-haves/agent-conventions.test.d.ts +40 -0
  87. package/build/src/types/tests/cli/scaffold/app/android.test.d.ts +2 -0
  88. package/build/src/types/tests/cli/utility/changelog.test.d.ts +48 -45
  89. package/build/src/types/tests/cli/utility/configure.test.d.ts +1 -0
  90. package/build/src/types/tests/cli/utility/run-scripts.test.d.ts +29 -0
  91. package/build/src/types/tests/lib/env-profiles.test.d.ts +20 -0
  92. package/build/src/types/tests/scaffold-output-contract.test.d.ts +27 -0
  93. package/build/templates/generators/must-haves/agent-conventions/AGENTS.md +8 -5
  94. package/build/templates/generators/must-haves/agent-conventions/CLAUDE.md +8 -5
  95. package/build/templates/generators/must-haves/agent-conventions/conventions/csharp.md +6 -6
  96. package/build/templates/generators/must-haves/agent-conventions/conventions/go.md +241 -0
  97. package/build/templates/generators/must-haves/agent-conventions/conventions/nova.md +155 -0
  98. package/build/templates/generators/must-haves/agent-conventions/conventions/python.md +7 -7
  99. package/build/templates/generators/must-haves/agent-conventions/conventions/rust.md +227 -0
  100. package/build/templates/generators/must-haves/agent-conventions/conventions/swift.md +9 -9
  101. package/build/templates/generators/must-haves/agent-conventions/conventions/typescript.md +145 -23
  102. package/build/templates/generators/must-haves/agent-conventions/conventions/universal.md +112 -103
  103. package/build/templates/generators/must-haves/ignore-files/gitignore +1 -0
  104. package/build/templates/scaffold/app/android/package.json +1 -1
  105. package/build/templates/scaffold/app/apple/Sources/App.swift +15 -2
  106. package/build/templates/scaffold/app/apple/Sources/ContentView.swift +6 -6
  107. package/build/templates/scaffold/app/apple/Sources/Localizable.xcstrings +75 -0
  108. package/build/templates/scaffold/app/apple/Tests/AppTests.swift +14 -2
  109. package/build/templates/scaffold/app/apple/package.json +1 -1
  110. package/build/templates/scaffold/app/astro/package.json +1 -1
  111. package/build/templates/scaffold/app/astro/src/i18n/en.json +48 -0
  112. package/build/templates/scaffold/app/astro/src/pages/index.astro +31 -30
  113. package/build/templates/scaffold/app/discord-bot/package.json +1 -1
  114. package/build/templates/scaffold/app/express/package.json +1 -1
  115. package/build/templates/scaffold/app/nextjs/package.json +1 -1
  116. package/build/templates/scaffold/app/nextjs/src/app/[lang]/dictionaries/en.json +31 -0
  117. package/build/templates/scaffold/app/nextjs/src/app/[lang]/dictionaries.ts +33 -0
  118. package/build/templates/scaffold/app/nextjs/src/app/[lang]/layout.tsx +92 -0
  119. package/build/templates/scaffold/app/nextjs/src/app/{page.tsx → [lang]/page.tsx} +54 -34
  120. package/build/templates/scaffold/app/nextjs/src/i18n/config.ts +42 -0
  121. package/build/templates/scaffold/app/nextjs/src/proxy.ts +56 -0
  122. package/build/templates/scaffold/app/nextjs/src/types/app/[lang]/dictionaries.d.ts +21 -0
  123. package/build/templates/scaffold/app/nextjs/src/types/app/[lang]/layout.d.ts +63 -0
  124. package/build/templates/scaffold/app/nextjs/src/types/app/[lang]/page.d.ts +22 -0
  125. package/build/templates/scaffold/app/nextjs/src/types/i18n/config.d.ts +22 -0
  126. package/build/templates/scaffold/app/nextjs/src/types/proxy.d.ts +30 -0
  127. package/build/templates/scaffold/app/vite/package.json +2 -2
  128. package/build/templates/scaffold/app/vite/vite.config.mts +3 -0
  129. package/build/templates/scaffold/docs/docusaurus/package.json +2 -2
  130. package/build/templates/scaffold/docs/docusaurus/src/pages/index.tsx +81 -20
  131. package/build/templates/scaffold/docs/docusaurus/vitest.config.mts +9 -0
  132. package/build/templates/scaffold/package/github-action/package.json +1 -1
  133. package/build/templates/scaffold/package/homebridge/package.json +1 -1
  134. package/build/templates/scaffold/package/pfsense/package.json +1 -1
  135. package/build/templates/scaffold/package/pfsense/port/files/usr/local/pkg/[__WORKSPACE_NAME__].inc +10 -0
  136. package/build/templates/scaffold/package/pfsense-root/.github/workflows/pfsense-[__WORKSPACE_NAME__].yml +62 -0
  137. package/build/templates/scaffold-options/app/android-launchpad/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/ui/main/MainScreen.kt +40 -34
  138. package/build/templates/scaffold-options/app/android-native/.gitattributes +2 -0
  139. package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/MainActivity.kt +16 -2
  140. package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/NavigationKeys.kt +7 -1
  141. package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/data/DataRepository.kt +28 -4
  142. package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/theme/Color.kt +40 -6
  143. package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/theme/Theme.kt +22 -1
  144. package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/theme/Type.kt +8 -2
  145. package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/ui/main/MainScreenViewModel.kt +42 -6
  146. package/build/templates/scaffold-options/app/android-native/app/src/main/res/values/strings.xml +27 -0
  147. package/build/templates/scaffold-options/app/android-native/app/src/test/java/[__ANDROID_PACKAGE_PATH__]/ui/main/MainScreenViewModelTest.kt +31 -4
  148. package/build/templates/scaffold-options/app/astro/cloudflare/astro.config.mjs +7 -0
  149. package/build/templates/scaffold-options/app/astro/cloudflare/public/.assetsignore +15 -0
  150. package/build/templates/scaffold-options/app/astro/node/astro.config.mjs +7 -0
  151. package/build/templates/scaffold-options/app/astro/static/astro.config.mjs +7 -0
  152. package/build/templates/scaffold-options/docker-image/common/dockerignore +2 -0
  153. package/build/templates/scaffold-options/tool/serverless/cloudflare-workers/package.json +1 -1
  154. package/build/templates/scaffold-options/tool/serverless/vercel-functions/package.json +1 -1
  155. package/package.json +3 -2
  156. package/build/templates/scaffold/app/nextjs/src/app/layout.tsx +0 -46
  157. package/build/templates/scaffold/app/nextjs/src/types/app/layout.d.ts +0 -25
  158. package/build/templates/scaffold/app/nextjs/src/types/app/page.d.ts +0 -8
@@ -2,6 +2,12 @@
2
2
 
3
3
  Quotes: Single. Indentation: 2-space. File naming: kebab-case (e.g., `markdown-table.ts`, `cli-header.d.ts`).
4
4
 
5
+ This document is the human-readable source of truth for Nova's TypeScript and
6
+ JavaScript style. Nova's `novaRules` ESLint preset mechanically enforces the
7
+ applicable source rules, while `registerTypeDeclarationSuite` enforces the
8
+ source-to-`.d.ts` contract. Rules that require architectural judgment remain
9
+ review conventions rather than claims of automatic enforcement.
10
+
5
11
  ## Documentation Style
6
12
 
7
13
  - Comment syntax: `/** */`
@@ -9,6 +15,9 @@ Quotes: Single. Indentation: 2-space. File naming: kebab-case (e.g., `markdown-t
9
15
  - Param format: `@param {TypeName} name - Name.` (description matches the parameter name, capitalized, with a trailing period)
10
16
  - Return format: `@returns {TypeName}`
11
17
  - Include `@private` tag for private members.
18
+ - Every documentable class, function, method, field, enum, interface, type, and function-valued constant requires a leading JSDoc block. Declaration mirrors in `.d.ts` files use section comments instead of per-symbol blocks.
19
+ - After the summary and one blank line, include a 2–3 line body paragraph explaining why the declaration exists, who uses it, or when it matters. Keep each body line within 80 characters.
20
+ - Tags use this canonical order: `@param`, `@private`, `@returns`, `@since`, `@deprecated`. Repeated tags in the same group stay adjacent; distinct groups have exactly one blank line between them.
12
21
 
13
22
  ### JSDoc `@param` Alignment
14
23
 
@@ -54,12 +63,18 @@ The example below is for the file `src/cli/utility/changelog.ts`. The class is n
54
63
  /**
55
64
  * CLI - Utility - Changelog.
56
65
  *
66
+ * Coordinates changelog recording and release preparation for Nova workspaces.
67
+ * The CLI entry point keeps release state synchronized through one workflow.
68
+ *
57
69
  * @since UNRELEASED
58
70
  */
59
71
  export class Runner {
60
72
  /**
61
73
  * CLI - Utility - Changelog - Run.
62
74
  *
75
+ * Resolves the selected changelog mode and delegates to its implementation.
76
+ * Command callers use this method as the stable orchestration boundary.
77
+ *
63
78
  * @param {Cli_Utility_Changelog_Runner_Run_Options} options - Options.
64
79
  *
65
80
  * @returns {Cli_Utility_Changelog_Runner_Run_Returns}
@@ -72,6 +87,9 @@ export class Runner {
72
87
  /**
73
88
  * CLI - Utility - Changelog - Fetch Data.
74
89
  *
90
+ * Loads the release inputs needed by the active changelog operation.
91
+ * Keeping retrieval isolated makes orchestration failures easier to report.
92
+ *
75
93
  * @private
76
94
  *
77
95
  * @returns {Cli_Utility_Changelog_Runner_FetchData_Returns}
@@ -84,6 +102,9 @@ export class Runner {
84
102
  /**
85
103
  * CLI - Utility - Changelog - Format Line.
86
104
  *
105
+ * Produces one consistently formatted line for terminal output.
106
+ * The helper keeps presentation details out of release orchestration.
107
+ *
87
108
  * @param {Cli_Utility_Changelog_Runner_FormatLine_Prefix} prefix - Prefix.
88
109
  * @param {Cli_Utility_Changelog_Runner_FormatLine_Message} message - Message.
89
110
  *
@@ -177,6 +198,33 @@ export type Cli_Runner_Record_SelectedCategory = EntryCategory;
177
198
  import type { Cli_Runner_Record_SelectedCategory } from '@/types/cli/runner.d.ts';
178
199
  ```
179
200
 
201
+ ### Declaration Imports Are Named and Verbatim
202
+
203
+ Declaration files import types through top-of-file `import type` statements.
204
+ Do not use inline `import('...')` references, and do not rename a type imported
205
+ from another `.d.ts` file with `as`. The imported name is already canonical.
206
+
207
+ ```ts
208
+ // BAD — inline import type
209
+ export type Cli_Runner_Options = import('@/types/shared.d.ts').Shared_Options;
210
+
211
+ // BAD — canonical declaration name hidden by an alias
212
+ import type { Shared_Options as Options } from '@/types/shared.d.ts';
213
+
214
+ // GOOD — named, top-of-file, verbatim import
215
+ import type { Shared_Options } from '@/types/shared.d.ts';
216
+
217
+ export type Cli_Runner_Options = Shared_Options;
218
+ ```
219
+
220
+ ### Source and Declaration Section Coverage
221
+
222
+ Every source section that uses named types has a corresponding section in its
223
+ mirror `.d.ts` file, and every mirror section maps back to a real source
224
+ section. Removing or renaming a class, method, function, function-valued
225
+ constant, or `(string, fn)` scope requires updating its declaration section in
226
+ the same change.
227
+
180
228
  ### Type Ordering in `.d.ts` Files
181
229
 
182
230
  **Sections** are in alphabetical order by their full section prefix (path + class + method/function/(string, fn) chunks). **Within each section**, types are ordered by first-use, first-listed (first come, first serve): parameters first (used first in the signature), then return/typeguard (used next in the signature), then body variable types in the sequential order they appear in the method body. This is strictly code-order, NOT alphabetical.
@@ -814,18 +862,18 @@ selectedCategory = matchedCategory;
814
862
 
815
863
  Groups separated by a blank line, alphabetical within each group. Specifiers within each `import { ... }` must also be alphabetical.
816
864
 
817
- 1. Node built-ins (e.g., `child_process`, `fs`, `os`, `path`) — detected by name, `node:` prefix not required
865
+ 1. Node built-ins (e.g., `node:child_process`, `node:fs`, `node:os`, `node:path`) — always use the `node:` protocol
818
866
  2. Third-party packages (e.g., `chalk`, `prompts`)
819
867
  3. Local imports (e.g., `@/lib/utility`, `@/toolkit/logger`)
820
868
  4. `import type` from Node built-ins
821
869
  5. `import type` from third-party
822
870
  6. `import type` from local (`@/`, `./`, `../`)
823
871
 
824
- Type imports maintain the same node → third-party → local sub-ordering as regular imports. In practice, `.ts` source files only have group 6 (type imports from local `@/types/...`). Groups 4 and 5 only appear in `.d.ts` files (e.g., `import type { Dirent } from 'fs'`).
872
+ Type imports maintain the same node → third-party → local sub-ordering as regular imports. In practice, `.ts` source files only have group 6 (type imports from local `@/types/...`). Groups 4 and 5 only appear in `.d.ts` files (e.g., `import type { Dirent } from 'node:fs'`).
825
873
 
826
874
  ```ts
827
- import { promises as fs } from 'fs';
828
- import { resolve } from 'path';
875
+ import { promises as fs } from 'node:fs';
876
+ import { resolve } from 'node:path';
829
877
 
830
878
  import chalk from 'chalk';
831
879
  import prompts from 'prompts';
@@ -878,11 +926,11 @@ When a named import conflicts with a local variable, keep the import name unchan
878
926
 
879
927
  ```ts
880
928
  // BAD — namespace import when named exports are available
881
- import * as path from 'path';
929
+ import * as path from 'node:path';
882
930
  path.resolve(process.cwd(), 'config.json');
883
931
 
884
932
  // GOOD — named import (tree-shakeable)
885
- import { resolve } from 'path';
933
+ import { resolve } from 'node:path';
886
934
  resolve(process.cwd(), 'config.json');
887
935
 
888
936
  // GOOD — import keeps its name, local variable gets `current` prefix
@@ -946,7 +994,7 @@ export class Runner {
946
994
 
947
995
  Instance (per-caller state) — file `src/toolkit/markdown-table.ts`:
948
996
  ```ts
949
- export default class Runner {
997
+ class Runner {
950
998
  readonly #headers: Toolkit_MarkdownTable_Runner_Constructor_Headers;
951
999
 
952
1000
  public constructor(headers: ..., options?: ...) {
@@ -955,6 +1003,8 @@ export default class Runner {
955
1003
 
956
1004
  public addRow(row: ...): ... { }
957
1005
  }
1006
+
1007
+ export default Runner;
958
1008
  // Called as (consumer aliases the default import to a domain-specific local name):
959
1009
  // import MarkdownTable from '@/toolkit/markdown-table.js';
960
1010
  // new MarkdownTable(headers).addRow(row);
@@ -995,10 +1045,13 @@ static #populated: boolean = false;
995
1045
 
996
1046
  ### Export Rules
997
1047
 
998
- - `export default class` — public API classes (barrel indexes, package `exports`).
999
1048
  - `export class` — internal classes.
1000
1049
  - Default to `export class` (named export) — this is the preference.
1001
- - `export default class` only for public API classes — so consumers can choose named or default import style. It's an accommodation, not a preference.
1050
+ - Public API classes may use a standalone `export default Runner;` at the end
1051
+ of the file when a default export is part of the package contract.
1052
+ - Never attach a declaration directly to `export default`. Declare the class,
1053
+ function, or value first, then export it in a separate statement at the
1054
+ bottom.
1002
1055
 
1003
1056
  ### Method Ordering
1004
1057
 
@@ -1089,7 +1142,9 @@ private static validate(value: string | number): ValidateReturns {
1089
1142
 
1090
1143
  ### No Rest Parameters
1091
1144
 
1092
- List function parameters explicitly. Rest parameters (`...args`) obscure the expected inputs and bypass arity checks. Variadic utility functions (e.g., logging wrappers) are an acceptable exception.
1145
+ List function parameters explicitly. Rest parameters (`...args`) obscure the
1146
+ expected inputs and bypass arity checks. Nova's shared preset has no allow list,
1147
+ so there are no source-level exceptions.
1093
1148
 
1094
1149
  ```ts
1095
1150
  // BAD — rest parameters
@@ -1112,9 +1167,12 @@ Reflect.set(target, key, value);
1112
1167
  target[key] = value;
1113
1168
  ```
1114
1169
 
1115
- ### Dot Notation for Method Calls
1170
+ ### Property and Method Access
1116
1171
 
1117
- Don't call methods using bracket notation with static string keys. Use dot notation for readability. Bracket notation for property *reads* on `Record`/plain objects is fine — this applies only to method *calls*.
1172
+ Use bracket notation for project-defined plain-object property reads. Use dot
1173
+ notation for class instances, built-in or third-party declarations, and method
1174
+ calls. Dynamic keys remain computed. Assign dynamic properties with
1175
+ `Reflect.set()` rather than bracket assignment.
1118
1176
 
1119
1177
  ```ts
1120
1178
  // BAD — bracket notation for method call
@@ -1130,6 +1188,9 @@ obj[methodName]();
1130
1188
 
1131
1189
  // OK — bracket notation for property reads on Record/plain objects
1132
1190
  const configItems = config['items'] as Runner_Filter_Items;
1191
+
1192
+ // GOOD — project-defined plain-object property read
1193
+ const workspaceName = workspaceConfig['name'];
1133
1194
  ```
1134
1195
 
1135
1196
  ### No Exponentiation Operator
@@ -1148,7 +1209,8 @@ value = Math.pow(value, 10);
1148
1209
 
1149
1210
  ### No Binary, Octal, or Hexadecimal Literals
1150
1211
 
1151
- Use `parseInt()` with an explicit radix instead of numeric literal prefixes. Hex literals for color codes, bit masks, and hardware registers are an acceptable exception.
1212
+ Use `parseInt()` with an explicit radix instead of numeric literal prefixes.
1213
+ Nova's shared preset disables binary, octal, and hexadecimal exceptions.
1152
1214
 
1153
1215
  ```ts
1154
1216
  // BAD
@@ -1322,9 +1384,12 @@ rawPaths.map((rawPath) => ...)
1322
1384
  allowedPolicies.map((allowedPolicy) => ...)
1323
1385
  ```
1324
1386
 
1325
- ### No Destructuring in Callback Parameters
1387
+ ### No Destructuring
1326
1388
 
1327
- Use the singular of the collection as the param, then access via index inside a block body with intermediate constants.
1389
+ Do not destructure variable declarations, assignments, function parameters,
1390
+ callback parameters, or `for...of` loop variables. Use the singular of the
1391
+ collection as the parameter or loop variable, then access its members through
1392
+ named intermediate constants.
1328
1393
 
1329
1394
  ```ts
1330
1395
  // BAD — destructuring in callback param
@@ -1345,15 +1410,18 @@ validCategories.find(
1345
1410
  )
1346
1411
  ```
1347
1412
 
1348
- Note: `for...of` destructuring is used with `Object.entries()` (which returns tuples), but NOT with Maps. For Maps, use `entry[0]`/`entry[1]` pattern:
1413
+ The same rule applies to tuples from `Object.entries()` and Maps:
1349
1414
  ```ts
1350
- // GOOD — Object.entries() destructuring (returns tuples)
1415
+ // BAD — destructuring in any for...of loop
1351
1416
  for (const [key, entry] of Object.entries(schedule)) { ... }
1352
-
1353
- // BAD — Map destructuring
1354
1417
  for (const [categoryName, categoryItems] of grouped) { ... }
1355
1418
 
1356
- // GOOD — Map iteration without destructuring
1419
+ // GOOD — explicit tuple access
1420
+ for (const scheduleEntry of Object.entries(schedule)) {
1421
+ const scheduleEntryKey = scheduleEntry[0];
1422
+ const scheduleEntryValue = scheduleEntry[1];
1423
+ }
1424
+
1357
1425
  for (const entry of grouped) {
1358
1426
  const entryCategory = entry[0];
1359
1427
  const entryItems = entry[1];
@@ -1384,6 +1452,9 @@ const eligibleConfigPolicy = eligibleConfig.policy;
1384
1452
  - **Block body** (`=> { ... return; }`): When accessing properties/elements of the callback param, or when multiple statements needed.
1385
1453
  - **Expression body** (`=> value`): When the callback is a direct comparison or single method call on a primitive.
1386
1454
 
1455
+ Concise arrow bodies may contain at most two chained calls and one nested arrow.
1456
+ Anything more complex uses a block body even when it could fit on one line.
1457
+
1387
1458
  ```ts
1388
1459
  // Block body — accessing tuple elements, multiple properties
1389
1460
  items.map((item) => {
@@ -1485,7 +1556,10 @@ return items.filter((item) => {
1485
1556
 
1486
1557
  ### Explicit `return;` in Void Functions
1487
1558
 
1488
- Every void function and method must end with an explicit `return;` statement. Arrow function callbacks, constructors, and setters are acceptable exceptions.
1559
+ Every non-empty block-bodied function or method that does not return a value
1560
+ must end with an explicit `return;` statement. This includes arrow callbacks,
1561
+ constructors, and setters. Empty bodies and concise arrows have no trailing
1562
+ statement and are therefore exempt.
1489
1563
 
1490
1564
  ```ts
1491
1565
  // BAD — implicit return
@@ -1652,10 +1726,12 @@ Use `Promise.all` for parallel execution. Cleaner than separate task variables,
1652
1726
  // GOOD — Promise.all
1653
1727
  const packageJsonPath = resolve(process.cwd(), 'package.json');
1654
1728
 
1655
- const [data, packageJsonRaw] = await Promise.all([
1729
+ const results: Runner_Run_Results = await Promise.all([
1656
1730
  Runner.fetchData(),
1657
1731
  fs.readFile(packageJsonPath, 'utf-8'),
1658
1732
  ]);
1733
+ const data: Runner_Run_Data = results[0];
1734
+ const packageJsonRaw: Runner_Run_PackageJsonRaw = results[1];
1659
1735
 
1660
1736
  // BAD — .then() chains (hard to read)
1661
1737
  // BAD — separate task variables (dangling promises on rejection)
@@ -1721,7 +1797,8 @@ const text = lines.join('\n');
1721
1797
 
1722
1798
  ### No `javascript:` URLs
1723
1799
 
1724
- Disallow `javascript:` URLs. Legacy anchor elements that must prevent navigation without `href="#"` may use `javascript:void(0)` as an acceptable exception.
1800
+ Disallow every `javascript:` URL. Nova's shared preset has no allowed patterns.
1801
+ Use a button for actions or a real route for navigation.
1725
1802
 
1726
1803
  ```ts
1727
1804
  // BAD
@@ -1775,6 +1852,51 @@ const LIB_REGEX_PATTERN_DIGITS = /\d+/;
1775
1852
  const allDigits = new RegExp(LIB_REGEX_PATTERN_DIGITS, 'g');
1776
1853
  ```
1777
1854
 
1855
+ ## Mechanical Enforcement Map
1856
+
1857
+ The convention explains intent; these registries define what Nova currently
1858
+ checks. Keep this map synchronized with `novaRules` and
1859
+ `registerTypeDeclarationSuite`. Adding, removing, or renaming an enabled rule
1860
+ requires updating this document in the same change.
1861
+
1862
+ ### Nova ESLint Rules
1863
+
1864
+ | Area | Enabled rules |
1865
+ |----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
1866
+ | Control flow and patterns | `@cbnventures/nova/no-assign-then-return`, `@cbnventures/nova/no-await-in-loop`, `@cbnventures/nova/no-boolean-var-for-if`, `@cbnventures/nova/no-use-before-define`, `@cbnventures/nova/require-explicit-return`, `@cbnventures/nova/switch-case-blocks` |
1867
+ | Object and call access | `@cbnventures/nova/no-bracket-assignment`, `@cbnventures/nova/no-bracket-method-call`, `@cbnventures/nova/require-bracket-property-access` |
1868
+ | TypeScript contracts | `@cbnventures/nova/no-catch-unknown-annotation`, `@cbnventures/nova/no-explicit-any`, `@cbnventures/nova/no-inline-type-annotation`, `@cbnventures/nova/no-shared-type-import`, `@cbnventures/nova/require-type-naming`, `@cbnventures/nova/require-undefined-init` |
1869
+ | Syntax and safety | `@cbnventures/nova/no-default-export-declaration`, `@cbnventures/nova/no-destructuring`, `@cbnventures/nova/no-implicit-boolean`, `@cbnventures/nova/no-numeric-literals`, `@cbnventures/nova/no-optional-chaining`, `@cbnventures/nova/no-rest-params`, `@cbnventures/nova/no-script-url` |
1870
+ | Formatting and readability | `@cbnventures/nova/no-complex-arrow-concise`, `@cbnventures/nova/no-multiline-strings`, `@cbnventures/nova/no-raw-text-in-code`, `@cbnventures/nova/no-template-curly-in-string`, `@cbnventures/nova/no-ternary-in-template-literal`, `@cbnventures/nova/require-import-order`, `@cbnventures/nova/require-multiline-condition-groups`, `@cbnventures/nova/require-multiline-conditions`, `@cbnventures/nova/require-padding-lines`, `@cbnventures/nova/require-ternary-parens` |
1871
+ | JSDoc | `@cbnventures/nova/require-jsdoc-body`, `@cbnventures/nova/require-jsdoc-hierarchy`, `@cbnventures/nova/require-jsdoc-param-alignment`, `@cbnventures/nova/require-jsdoc-param-name`, `@cbnventures/nova/require-jsdoc-presence`, `@cbnventures/nova/require-jsdoc-private`, `@cbnventures/nova/require-jsdoc-returns`, `@cbnventures/nova/require-jsdoc-since`, `@cbnventures/nova/require-jsdoc-tag-order` |
1872
+ | Naming and modules | `@cbnventures/nova/require-hash-private`, `@cbnventures/nova/require-kebab-case-filename`, `@cbnventures/nova/require-naming-convention`, `@cbnventures/nova/require-node-protocol` |
1873
+ | Nova-specific diagnostics | `@cbnventures/nova/no-logger-dev` |
1874
+ | Regular expressions | `@cbnventures/nova/no-regex-literal-flags`, `@cbnventures/nova/no-regex-literals` |
1875
+
1876
+ `@cbnventures/nova/no-raw-text-in-code` applies to MDX rather than TypeScript
1877
+ syntax, but remains listed because it is part of the same enabled preset.
1878
+
1879
+ ### Vitest Type-Declaration Inspectors
1880
+
1881
+ | Toggle | Contract |
1882
+ |------------------------------------------|---------------------------------------------------------------------------|
1883
+ | `inspector-cross-section-references` | Declaration sections only reference their own or imported types. |
1884
+ | `inspector-dts-import-verbatim` | Types imported from `.d.ts` files keep their canonical names. |
1885
+ | `inspector-no-inline-import-types` | Declaration files use top-of-file named type imports. |
1886
+ | `inspector-section-alphabetical` | Declaration sections remain alphabetical. |
1887
+ | `inspector-first-come-first-serve-order` | Types inside a section follow first use in source. |
1888
+ | `inspector-object-property-types` | Object properties use earlier parent-prefixed named types. |
1889
+ | `inspector-section-coverage` | Source and declaration sections cover one another in both directions. |
1890
+ | `inspector-variable-type-symmetry` | Parameters, returns, and body variables use their mirrored named aliases. |
1891
+ | `inspector-identifier-vs-filename` | Top-level identifiers do not duplicate the file name. |
1892
+ | `inspector-filename-validation` | Source and declaration paths follow the supported naming grammar. |
1893
+ | `inspector-standalone-type-files` | Shared declarations follow the standalone type-file rules. |
1894
+
1895
+ Nova's other Vitest suites validate repository contracts such as environment
1896
+ variables, frontmatter, links, Markdown tables, package scripts, and
1897
+ terminology. They are intentionally documented in their own convention or rule
1898
+ pages instead of being presented as TypeScript language rules.
1899
+
1778
1900
  ## TSConfig Conventions
1779
1901
 
1780
1902
  ```jsonc
@@ -4,9 +4,20 @@ Rules that apply across all programming languages and platforms.
4
4
 
5
5
  ## AI Agent Behavior
6
6
 
7
+ ### Supported Agents
8
+
9
+ Nova officially supports Claude Code and Codex. Follow the shared rules in this
10
+ file on both platforms, then apply the explicitly labeled platform instructions
11
+ when their tools or interaction models differ.
12
+
13
+ Other coding agents may use these conventions, but they must translate the
14
+ Claude Code and Codex instructions to their closest supported capabilities.
15
+
7
16
  ### Task Tracking
8
17
 
9
- Every top-level user request must be tracked as a task. Break multi-step requests into discrete sub-tasks. Mark each task as in-progress before starting and completed when done.
18
+ Every top-level user request must be tracked as a task. Break multi-step requests
19
+ into discrete sub-tasks. Mark each task as in progress before starting and
20
+ completed when done.
10
21
 
11
22
  **Claude Code:**
12
23
 
@@ -17,13 +28,63 @@ Every top-level user request must be tracked as a task. Break multi-step request
17
28
  | `TaskList` | List all tasks to find the next available work. |
18
29
  | `TaskUpdate` | Update status (`pending` / `in_progress` / `completed`), add dependencies. |
19
30
 
20
- **Codex CLI / Cursor / Other agents:**
31
+ **Codex:**
32
+
33
+ | Tool / command | Purpose |
34
+ |----------------|----------------------------------------------------------------------------------------------|
35
+ | `update_plan` | Create and maintain the current task's ordered steps and their progress. |
36
+ | `create_goal` | Start a persistent goal after the user explicitly requests Goal mode. |
37
+ | `get_goal` | Read the active goal's objective, status, budget, and progress. |
38
+ | `update_goal` | Complete an achieved goal, pause it when requested, or report a repeated blocking condition. |
39
+ | `/plan` | Let the user request investigation and planning before implementation. |
40
+ | `/goal` | Let the user start or inspect a persistent objective. |
41
+ | `/goal pause` | Let the user pause the active goal. |
42
+ | `/goal resume` | Let the user resume a paused goal. |
43
+ | `/goal clear` | Let the user remove the active goal. |
44
+
45
+ Use `update_plan` for ordinary multi-step work when the tool is available. Use a
46
+ persistent goal only when the user explicitly requests one or invokes `/goal`;
47
+ do not create a goal for a one-off edit.
48
+
49
+ **Unsupported agents:**
50
+
51
+ Use the platform's closest task-tracking equivalent. If none exists, maintain a
52
+ checklist in progress updates. State what is about to happen and confirm each
53
+ completed checkpoint before moving on.
54
+
55
+ ### Scope Confirmation
56
+
57
+ Confirm the understood scope and intended approach before acting on every user
58
+ request. If the user already explicitly requested implementation, this
59
+ confirmation is a progress update, not a second approval gate. Wait only when an
60
+ unresolved decision would materially change the result or requires authority the
61
+ user has not granted.
62
+
63
+ Honor the platform's active permission mode. Auto or auto-accept modes allow
64
+ explicitly authorized work to continue without repeated approval prompts; they
65
+ do not expand the user's requested scope.
21
66
 
22
- If your platform does not provide dedicated task tracking tools, maintain a checklist in your working memory or output. State what you are about to do before starting and confirm completion before moving on.
67
+ ### Working Copy and Authorization
68
+
69
+ Inspect the working copy before material edits. Preserve unrelated user changes,
70
+ including uncommitted and untracked files, and never revert or reformat them as
71
+ part of another task.
72
+
73
+ Do not commit, tag, push, publish, deploy, delete material data, or mutate an
74
+ external system unless the user explicitly authorizes that action. Resolve exact
75
+ targets with read-only checks before any destructive operation.
23
76
 
24
77
  ### Command Output Caching
25
78
 
26
- When a command produces output that may be referenced later, save it to a file in the agent's designated temporary directory. Read from the cached file instead of re-running the command. Do not rely on conversation memory for command output — files survive context compaction.
79
+ Cache command output when it is expensive to reproduce, nondeterministic,
80
+ crash-prone, likely to be truncated, or needed after a pause or context
81
+ compaction. Examples include long builds, virtual-machine runs, crash logs,
82
+ repository-wide audits, and release verification.
83
+
84
+ Store cached output in a task-specific temporary directory, read from that file
85
+ instead of rerunning the command, and remove it when the evidence is no longer
86
+ needed. Do not cache trivial commands such as `pwd`, `git status`, or small
87
+ searches.
27
88
 
28
89
  ### File Writes
29
90
 
@@ -33,7 +94,11 @@ Reading files via the shell (`cat`, `head`, `tail`, `grep`, `rg`) is fine. The r
33
94
 
34
95
  ### Command Transparency
35
96
 
36
- Run commands from explicit, full directory paths so every invocation is unambiguous. Prefix commands with `cd` to the target directory so the working directory is visible in the output.
97
+ Run shell commands from explicit, full directory paths so every invocation is
98
+ unambiguous. Prefix shell commands with `cd` to the absolute target directory so
99
+ the working directory is visible in the output. When a native tool exposes a
100
+ dedicated working-directory field instead of a shell, set that field and report
101
+ the directory in the progress update.
37
102
 
38
103
  ```bash
39
104
  # BAD — ambiguous which workspace
@@ -43,15 +108,26 @@ npm run build
43
108
  cd /path/to/packages/nova && npm run build
44
109
  ```
45
110
 
46
- ### Web Browser Debugging
111
+ ### Browser and UI Work
47
112
 
48
- For visual testing and web page interaction, prefer the Claude-in-Chrome MCP tools (`mcp__claude-in-chrome__*` — `tabs_*`, `navigate`, `javascript_tool`, `read_page`, `read_console_messages`, etc.) when available. They drive the user's real Chrome session and provide richer page inspection.
113
+ Use the narrowest available capability before general computer control.
114
+
115
+ **Claude Code:**
49
116
 
50
- If the Claude-in-Chrome MCP is not available, fall back to Vercel's `agent-browser` command for headless rendering and interaction. Run `agent-browser --help` for available commands.
117
+ 1. Prefer a purpose-built connector or MCP tool.
118
+ 2. Use Claude in Chrome or Desktop Preview for rendered pages and interaction.
119
+ 3. Use computer use only when a narrower tool cannot complete the task.
120
+ 4. Use `agent-browser` for headless checks or screenshots that must be saved as files.
51
121
 
52
- One exception to the MCP-first preference: Claude-in-Chrome screenshots are returned inline in the conversation and cannot be written to disk. When a screenshot must be saved to a file — to attach to a commit, produce an artifact, or include in a report — use `agent-browser` to capture it even when the MCP is available.
122
+ **Codex:**
53
123
 
54
- Do not use `curl`, `wget`, or other plain HTTP clients for tasks that require rendering, clicking, or inspecting a page.
124
+ 1. Prefer a purpose-built connector or app tool.
125
+ 2. Use the Codex in-app browser or preview for rendered pages.
126
+ 3. Use browser control or computer-use automation for interaction.
127
+ 4. Use available headless browser tooling when those surfaces are unavailable or an artifact must be saved.
128
+
129
+ On both platforms, use plain HTTP clients for API and transport checks, not for
130
+ tasks that require rendering, clicking, visual inspection, or browser state.
55
131
 
56
132
  ### Web Research
57
133
 
@@ -74,26 +150,25 @@ When the user corrects you, state what you're actually updating, why the prior a
74
150
  ### Scope
75
151
 
76
152
  - **Only apply version and changelog rules to user-requested product changes.** Process-only edits, tooling updates, and non-product changes do not trigger version bumps or changelog entries.
77
- - **Confirm your understanding before making changes.** For each user request, state exactly what you understood and what you plan to do before starting work.
153
+ - **Match the implementation to the requested outcome.** Do not add neighboring features, refactors, or cleanup unless they are necessary to complete the authorized task.
78
154
 
79
155
  ### Per-Change Mechanics
80
156
 
81
- - **Update the changelog with every change.** Add bullet points under the current version section. If the platform uses build numbers, recalculate using the bullet-count formula.
82
- - **Build after every change.** Run the platform build command and verify success before moving on.
157
+ - **Use the project's changelog mechanism.** Record user-visible product changes through the repository's configured tooling. Do not manually edit generated release artifacts or infer a release format from memory.
158
+ - **Verify every logical change.** After each approved logical change or repository batch, run proportionate focused checks and the applicable build before starting unrelated work. A multi-file implementation is one logical checkpoint, not one checkpoint per file.
83
159
  - **Do not add changelog entries for version bumps alone** or for incidental implementation fallout unless there is a clear user-visible behavior change.
84
160
 
85
- ### Version Lifecycle
161
+ ### Version and Release Boundaries
86
162
 
87
- - **Keep the version unchanged while working within a release line.** Do not bump the version until the user signals a new release.
88
- - **Start a new version only when the working tree is clean** — all current changes committed and `git status --short` is empty.
89
- - **When starting a new version, ask first.** Confirm whether the bump is major, minor, or bugfix (semver). Then create a new changelog section, bump the version, and carry forward the prior build number.
90
- - **Do not commit a version bump by itself.** Keep version bump changes in the working copy until at least one user-requested change is included. Do not run a build when only starting a new version line.
163
+ - **Read the repository's configured strategy before changing versions.** Do not assume semver, calver, build-number behavior, workspace release roles, or version-file locations.
164
+ - **Do not start or cut a release without explicit authorization.** A product change does not independently authorize a version bump, release cut, commit, tag, push, publication, or deployment.
165
+ - **Keep generated release state synchronized through project tooling.** Do not hand-edit version stamps or released changelog output unless the repository explicitly documents that workflow and the user requests it.
91
166
 
92
167
  ### Wrapping Up
93
168
 
94
- - **Keep working until the user says "all done."** Continue executing per-change bumps and builds until explicitly told to stop.
95
- - **On "all done":** consolidate the changelog, recalculate the build number (if applicable), sync the version across all version files, and commit with a thematic subject line listing 3-5 themes in imperative form (e.g. `Add reconnect action, bandwidth polish, persistent TOTP lockout, and docs screenshots`). Do not use the version number as the subject (no `1.2.0 (295)` style); the version pointer lives in the tag, not the subject. Do not add co-author credits.
96
- - **Keep version numbers and CHANGELOG.md synchronized** at all times before commit.
169
+ - **Continue until the requested outcome is genuinely complete.** Stop at explicit user review, approval, or manual-intervention boundaries.
170
+ - **Report evidence.** Summarize the changed files, checks and builds run, unresolved issues, and any manual action that remains.
171
+ - **Do not infer commit authorization from completion.** Prepare a commit message or release notes when requested, but leave repository and remote state unchanged unless the user explicitly asks for the corresponding action.
97
172
 
98
173
  ## General Code Style
99
174
 
@@ -111,6 +186,8 @@ When the user corrects you, state what you're actually updating, why the prior a
111
186
  | Language | Quotes | Indentation |
112
187
  |-------------------------|----------------------------------|-------------|
113
188
  | TypeScript / JavaScript | Single | 2-space |
189
+ | Go | Double (string literals) | Tabs |
190
+ | Rust | Double (string literals) | 4-space |
114
191
  | Swift | Double (only option) | 4-space |
115
192
  | Java | Double (only option) | 4-space |
116
193
  | Kotlin | Double (only option) | 4-space |
@@ -123,18 +200,20 @@ When the user corrects you, state what you're actually updating, why the prior a
123
200
 
124
201
  ### File Naming
125
202
 
126
- | Language | Convention | Example |
127
- |-------------------------|----------------------------------|---------------------------------------------|
128
- | TypeScript / JavaScript | kebab-case | `markdown-table.ts`, `cli-header.d.ts` |
129
- | Swift | PascalCase + role suffix | `TunnelFormView.swift`, `TunnelModel.swift` |
130
- | Java | PascalCase matching class name | `EntityRepository.java` |
131
- | Kotlin | PascalCase matching class name | `EntityRepository.kt` |
132
- | C# | PascalCase matching class name | `EntityRepository.cs` |
133
- | PHP | PascalCase (PSR-4) or snake_case | `EntityRepository.php` |
134
- | Python | snake_case (PEP 8) | `entity_repository.py` |
135
- | CSS | kebab-case | `user-profile.css` |
136
- | Docker | kebab-case | `api-gateway.Dockerfile` |
137
- | Shell | kebab-case | `backup-config.sh` |
203
+ | Language | Convention | Example |
204
+ |-------------------------|----------------------------------|-----------------------------------------------|
205
+ | TypeScript / JavaScript | kebab-case | `markdown-table.ts`, `cli-header.d.ts` |
206
+ | Go | lowercase snake_case | `release_client.go`, `release_client_test.go` |
207
+ | Rust | snake_case | `release_client.rs` |
208
+ | Swift | PascalCase + role suffix | `TunnelFormView.swift`, `TunnelModel.swift` |
209
+ | Java | PascalCase matching class name | `EntityRepository.java` |
210
+ | Kotlin | PascalCase matching class name | `EntityRepository.kt` |
211
+ | C# | PascalCase matching class name | `EntityRepository.cs` |
212
+ | PHP | PascalCase (PSR-4) or snake_case | `EntityRepository.php` |
213
+ | Python | snake_case (PEP 8) | `entity_repository.py` |
214
+ | CSS | kebab-case | `user-profile.css` |
215
+ | Docker | kebab-case | `api-gateway.Dockerfile` |
216
+ | Shell | kebab-case | `backup-config.sh` |
138
217
 
139
218
  ## Documentation Style
140
219
 
@@ -156,73 +235,3 @@ When the user corrects you, state what you're actually updating, why the prior a
156
235
  - Members: `ClassName - MemberName.`
157
236
  - Nested types: `OuterClass.InnerClass - MemberName.`
158
237
  - Enum cases: `EnumName - CaseName.`
159
-
160
- ## Platform Build Rules
161
-
162
- ### Apple (Xcode)
163
-
164
- - **Version file:** `project.pbxproj` (`MARKETING_VERSION` + `CURRENT_PROJECT_VERSION`)
165
- - **Build number:** Yes — equals total count of changelog bullet lines across `CHANGELOG.md`
166
- - **Build command:** `xcodebuild build` (with project-specific scheme/destination)
167
- - **Changelog header:** `## X.Y.Z (build) - YYYY-MM-DD`
168
-
169
- ### TypeScript / JavaScript (Node.js)
170
-
171
- - **Version file:** `package.json` `version`
172
- - **Build number:** No
173
- - **Build command:** `npm run build`
174
- - **Changelog header:** `## X.Y.Z - YYYY-MM-DD`
175
-
176
- ### Android (Gradle)
177
-
178
- - **Version file:** `build.gradle` (`versionName` + `versionCode`)
179
- - **Build number:** Yes — equals total count of changelog bullet lines across `CHANGELOG.md`
180
- - **Build command:** `./gradlew assembleDebug`
181
- - **Changelog header:** `## X.Y.Z (build) - YYYY-MM-DD`
182
-
183
- ### Windows (.NET)
184
-
185
- - **Version file:** `.csproj` (`Version`)
186
- - **Build number:** No
187
- - **Build command:** `dotnet build`
188
- - **Changelog header:** `## X.Y.Z - YYYY-MM-DD`
189
-
190
- ### PHP (Composer)
191
-
192
- - **Version file:** `composer.json` `version`
193
- - **Build number:** No
194
- - **Build command:** `composer test`
195
- - **Changelog header:** `## X.Y.Z - YYYY-MM-DD`
196
-
197
- ### Python (pip / Poetry)
198
-
199
- - **Version file:** `pyproject.toml` `version`
200
- - **Build number:** No
201
- - **Build command:** `python -m build`
202
- - **Changelog header:** `## X.Y.Z - YYYY-MM-DD`
203
-
204
- ### Docker
205
-
206
- - **Version file:** `Dockerfile` `ARG VERSION` or none
207
- - **Build number:** No
208
- - **Build command:** `docker build .`
209
- - **Changelog header:** `## X.Y.Z - YYYY-MM-DD`
210
-
211
- ## Release Notes Format
212
-
213
- ```markdown
214
- ## 1.2.0 - 2026-01-01
215
-
216
- ### UPDATED
217
- - Enhanced the changelog release summary output.
218
-
219
- ### FIXED
220
- - Fixed version bump calculation for major releases.
221
-
222
- ### ADDED
223
- - Added dry-run mode to the release command.
224
- ```
225
-
226
- - Use headings in this order: `### UPDATED`, `### FIXED`, `### ADDED`, `### REMOVED`.
227
- - Leave out any heading that has no entries.
228
- - Use only ASCII characters and standard US keyboard quotes.
@@ -7,6 +7,7 @@ local.properties
7
7
  .env
8
8
  .env.*
9
9
  !.env.sample
10
+ !.env.*.sample
10
11
 
11
12
  ##################################
12
13
  #### Operating System - Linux ####