@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
@@ -0,0 +1,155 @@
1
+ # Nova Conventions
2
+
3
+ Rules for agents and developers working in repositories managed by Nova. Read
4
+ this file with `universal.md`, the applicable language conventions,
5
+ `nova.config.json`, `VISION.md`, and `PROJECT_RULES.md`.
6
+
7
+ ## Source of Truth
8
+
9
+ - `nova.config.json` defines project identity, workspace roles, version
10
+ strategy, enabled recipes, workflows, deployment targets, and Nova behavior.
11
+ - `package.json` scripts are the public project interface. Use the root scripts
12
+ before invoking underlying tools directly.
13
+ - `VISION.md` defines product purpose and boundaries. `PROJECT_RULES.md` defines
14
+ repository-specific structure and exceptions.
15
+ - Generated files remain generated. Change the Nova template or configuration
16
+ that owns a file, then regenerate it; do not patch generated output as the
17
+ primary fix.
18
+ - Never infer a Nova contract from another consumer unless the user explicitly
19
+ asks for comparison or consistency across a named group of repositories.
20
+
21
+ ## Work from the Project Root
22
+
23
+ Run Nova from the repository root containing `nova.config.json`. Workspace
24
+ commands still use the root orchestration unless project rules explicitly say
25
+ otherwise.
26
+
27
+ ```bash
28
+ cd /absolute/path/to/project
29
+ npm run check
30
+ npm run build
31
+ ```
32
+
33
+ Do not bypass the root with direct workspace commands merely because they are
34
+ faster. Focused checks are useful during implementation, but the configured root
35
+ check and build remain the final repository contract.
36
+
37
+ ## Configuration
38
+
39
+ - Prefer `nova utility configure` for supported configuration changes. Every
40
+ supported `nova.config.json` field must remain editable through that utility.
41
+ - Read the current value before changing it; do not replace sibling settings or
42
+ custom workflow data while updating one field.
43
+ - Use `nova recipe nova-config normalize-order` only to normalize key order. It
44
+ does not decide project semantics.
45
+ - Do not place secrets, tokens, private keys, or credential paths in
46
+ `nova.config.json`. Use the vendor's official credential location or the
47
+ environment contract documented for that integration.
48
+
49
+ ## Command Boundaries
50
+
51
+ ### Generate
52
+
53
+ `nova generate` creates or synchronizes project-level files. It does not create
54
+ application or package workspaces. Configure prerequisites first, then run the
55
+ specific generator.
56
+
57
+ ### Recipe
58
+
59
+ `nova recipe <category>` opens that category's interactive menu. It is not a
60
+ batch command. Run a specific recipe when reviewing one transformation, or run
61
+ `nova utility run-recipes` to execute every individually enabled recipe in
62
+ registry order.
63
+
64
+ Recipes preserve existing project commands and content unless the documented
65
+ recipe contract explicitly owns them. They may add missing standard structure;
66
+ they must not silently replace a consumer's custom implementation.
67
+
68
+ ### Scaffold
69
+
70
+ `nova scaffold` creates a new Nova project or adds one supported workspace to an
71
+ existing Nova monorepo. Scaffolds collect all interactive answers before writing
72
+ files, install dependencies by default, register the workspace and platforms,
73
+ and leave project-level generators as separate opt-in work.
74
+
75
+ Treat scaffold templates as user-facing source code. Generated applications
76
+ must remain readable, editable, translation-ready where the platform supports
77
+ it, and free of tests that police Nova's template implementation after the user
78
+ starts customizing the project.
79
+
80
+ ### Utility
81
+
82
+ - `nova utility changelog --record` records a user-visible change.
83
+ - `nova utility changelog --release` applies the configured release strategy,
84
+ regenerates release state, and stamps supported unreleased annotations.
85
+ - `nova utility run-recipes` runs every enabled recipe.
86
+ - `nova utility run-workspaces <script>` executes the configured dependency
87
+ graph with the project's concurrency and cache settings.
88
+ - `nova utility run-scripts` coordinates related scripts inside one workspace.
89
+
90
+ Use command help and the generated docs for additional utilities. Do not invent
91
+ new aliases, categories, or command semantics from memory.
92
+
93
+ ## Changelog and Versioning
94
+
95
+ - Record changelog fragments through Nova's changelog command. Do not hand-edit
96
+ generated `CHANGELOG.md` release sections.
97
+ - Read the configured workspace policy and version strategy before proposing a
98
+ version. `freezable`, `trackable`, and `distributable` have different release
99
+ contracts; SemVer and CalVer have different next-version rules.
100
+ - `0.0.0` is the reserved freezable sentinel. Do not reuse it as a generic
101
+ starting version for trackable or distributable workspaces.
102
+ - Add `UNRELEASED` annotations only in syntaxes the Nova stamper supports and
103
+ only where the declaration convention requires one.
104
+ - A release command does not authorize commit, tag, push, publish, deployment,
105
+ or consumer rollout. Those remain separate user decisions.
106
+
107
+ ## Recipes and Generated State
108
+
109
+ - Recipe toggles are individual, not category-wide. Preserve each repository's
110
+ deliberate exceptions while moving shared defaults into Nova.
111
+ - Run recipes after configuration and templates are correct, not as a substitute
112
+ for understanding an unexplained diff.
113
+ - Review the working-copy diff after recipe execution. A recipe must not rewrite
114
+ unrelated custom scripts, deployment commands, documentation, or project
115
+ content.
116
+ - Use `--dry-run` when available to inspect a broad or unfamiliar operation
117
+ before allowing writes.
118
+
119
+ ## Linked Nova Development
120
+
121
+ Some Nova-owned consumers intentionally use `link-nova` so their checks exercise
122
+ the local Nova checkout before publication. Treat that as a maintainer workflow,
123
+ not a scaffold default or a requirement for third-party consumers.
124
+
125
+ - Preserve a repository's established `link-nova` integration when the project
126
+ is owned by the Nova maintainer and actively develops against Nova.
127
+ - Do not add it to generated scaffolds.
128
+ - Do not add it to client or third-party repositories unless the user explicitly
129
+ requests local Nova development there.
130
+ - Before a consumer release, replace development-only linkage with the published
131
+ Nova version through the repository's approved rollout workflow.
132
+
133
+ ## Verification
134
+
135
+ 1. Run focused checks for the affected workspace while iterating.
136
+ 2. Run the root `npm run check` after the logical change is complete.
137
+ 3. Run the root `npm run build` when the change affects emitted artifacts,
138
+ templates, packages, applications, or deployment output.
139
+ 4. Run scaffold contract coverage when a template, generator, dependency
140
+ snapshot, or scaffold option changes.
141
+ 5. Inspect generated files for user-facing quality; a passing snapshot does not
142
+ replace semantic review.
143
+
144
+ When a required service is installed but stopped, use the repository's supported
145
+ test harness to start it when authorized. Do not silently skip container-native
146
+ or platform-native validation merely because the engine was initially stopped.
147
+
148
+ ## Release Handoff
149
+
150
+ Before presenting release material, confirm the changelog command has produced
151
+ the intended released section and that check/build evidence belongs to the
152
+ current working copy. Present the repository's preferred commit message and the
153
+ complete GitHub release block separately. Do not include procedural phrases such
154
+ as “release Nova” or dependency-only upgrade summaries unless they describe the
155
+ actual user-visible change.
@@ -5,7 +5,7 @@ Quotes: Double (Black/Google convention). Indentation: 4-space. File naming: sna
5
5
  ## Documentation Style
6
6
 
7
7
  - Comment syntax: `"""` (Google-style)
8
- - Padding tag: `Version:\n 1.0.0` (Google-style custom section)
8
+ - Padding tag: `Since:\n UNRELEASED` (Google-style custom section) — tag new or changed API with the sentinel; Nova stamps the real version during the workspace release, so never hand-write a version number.
9
9
  - Param format: `Args:\n name: Name.` (description matches the parameter name, capitalized, with a trailing period)
10
10
  - Return format: `Returns:\n Type.`
11
11
  - Docstring starts with `"""` then a newline before the summary line.
@@ -18,8 +18,8 @@ class EntityRepository:
18
18
  """
19
19
  Entity Repository.
20
20
 
21
- Version:
22
- 1.0.0
21
+ Since:
22
+ UNRELEASED
23
23
  """
24
24
 
25
25
  def __init__(self, database):
@@ -29,8 +29,8 @@ class EntityRepository:
29
29
  Args:
30
30
  database: Database.
31
31
 
32
- Version:
33
- 1.0.0
32
+ Since:
33
+ UNRELEASED
34
34
  """
35
35
  self._database = database
36
36
 
@@ -44,8 +44,8 @@ class EntityRepository:
44
44
  Returns:
45
45
  Entity.
46
46
 
47
- Version:
48
- 1.0.0
47
+ Since:
48
+ UNRELEASED
49
49
  """
50
50
  return self._database.get(entity_id)
51
51
  ```
@@ -0,0 +1,227 @@
1
+ # Rust Conventions
2
+
3
+ Formatting: `rustfmt`. Linting: Clippy with the workspace's configured lint
4
+ levels. File and module naming: snake_case. Type and trait naming: PascalCase.
5
+
6
+ These rules preserve the intent of Nova's TypeScript conventions while using
7
+ idiomatic Rust. They do not translate TypeScript syntax mechanically.
8
+
9
+ ## Documentation Style
10
+
11
+ - Public items use Rustdoc comments (`///`); modules and crates use inner
12
+ Rustdoc comments (`//!`).
13
+ - Start with a one-sentence summary, then a 2–3 line body explaining why the
14
+ item exists, who uses it, or when it matters.
15
+ - Add standard sections such as `# Errors`, `# Panics`, and `# Safety` when the
16
+ contract exposes those behaviors.
17
+ - New or changed items end with `Since: UNRELEASED`. Nova stamps that sentinel
18
+ during the workspace release; never write the release version by hand.
19
+ - Document private items when their invariants, concurrency, unsafe behavior,
20
+ or side effects are not obvious from the implementation.
21
+
22
+ ### Example
23
+
24
+ ```rust
25
+ /// Publishes prepared release artifacts.
26
+ ///
27
+ /// Command handlers use this client after validation so provider access stays
28
+ /// separate from version preparation and local release state.
29
+ ///
30
+ /// # Errors
31
+ ///
32
+ /// Returns an error when the provider rejects or cannot receive the artifact.
33
+ ///
34
+ /// Since: UNRELEASED
35
+ pub trait PublishClient {
36
+ fn publish(&self, request: &PublishRequest) -> Result<(), PublishError>;
37
+ }
38
+
39
+ /// Publishes one validated artifact.
40
+ ///
41
+ /// The method adds artifact context while preserving the provider error as the
42
+ /// source so callers can inspect the complete failure chain.
43
+ ///
44
+ /// # Errors
45
+ ///
46
+ /// Returns an error when the configured client cannot publish the artifact.
47
+ ///
48
+ /// Since: UNRELEASED
49
+ pub fn publish(
50
+ client: &dyn PublishClient,
51
+ request: &PublishRequest,
52
+ ) -> Result<(), PublishError> {
53
+ client
54
+ .publish(request)
55
+ .map_err(|source| PublishError::Publish {
56
+ name: request.name.clone(),
57
+ source,
58
+ })
59
+ }
60
+ ```
61
+
62
+ ## Naming and Modules
63
+
64
+ - Crates, modules, functions, methods, local variables, and files use
65
+ snake_case.
66
+ - Structs, enums, traits, variants, and type aliases use PascalCase.
67
+ - Constants and statics use SCREAMING_SNAKE_CASE.
68
+ - Lifetimes use short lowercase names that communicate their relationship; use
69
+ descriptive names when several lifetimes coexist.
70
+ - Avoid project-invented abbreviations. Preserve established domain and Rust
71
+ initialisms when changing them would make the API less recognizable.
72
+ - Keep `mod.rs` only where the existing project intentionally uses that layout;
73
+ otherwise prefer `module.rs` plus `module/` children.
74
+
75
+ ## Imports and Visibility
76
+
77
+ - Group `use` declarations by standard library, external crates, then local
78
+ crate modules, separated by blank lines.
79
+ - Prefer explicit imports over glob imports. A prelude or test module may use a
80
+ glob only when that is its deliberate public contract.
81
+ - Keep visibility as narrow as possible: private first, then `pub(super)` or
82
+ `pub(crate)`, and `pub` only for the external contract.
83
+ - Re-export an item only when the parent module intentionally owns the public
84
+ path.
85
+
86
+ ## Ownership and Types
87
+
88
+ ### Borrow Before Cloning
89
+
90
+ - Accept borrowed values when the function only reads them.
91
+ - Return owned values when ownership must leave the function.
92
+ - Clone deliberately at an ownership boundary; do not add `.clone()` merely to
93
+ silence a borrow-checker error without understanding the lifetime.
94
+ - Prefer `&str` over `&String` and slices over borrowed `Vec` values.
95
+
96
+ ### Domain Types over Primitive Flags
97
+
98
+ Use enums, newtypes, and structs for states with distinct meaning. Avoid boolean
99
+ parameters whose meaning is unclear at the call site and raw strings for closed
100
+ sets of supported values.
101
+
102
+ ```rust
103
+ // BAD — intent is hidden at the call site.
104
+ publish(request, true)?;
105
+
106
+ // GOOD — the domain state is explicit.
107
+ publish(request, DeploymentEnvironment::Production)?;
108
+ ```
109
+
110
+ ### Traits at Real Boundaries
111
+
112
+ - Introduce a trait when multiple implementations, external integration, or a
113
+ test seam is part of the design—not only to wrap one function mechanically.
114
+ - Prefer static dispatch with generics unless runtime polymorphism is required.
115
+ - Keep traits small and behavior-focused.
116
+
117
+ ## Error Handling
118
+
119
+ - Use `Result` for recoverable failure and `Option` for absence.
120
+ - Propagate errors with `?` and add operation/subject context at system
121
+ boundaries.
122
+ - Preserve error sources. Structured libraries should expose typed errors;
123
+ applications may add broader contextual reports at their outer boundary.
124
+ - Do not use `unwrap()` or `expect()` in production paths unless an invariant is
125
+ proven locally and the message explains why violation is impossible.
126
+ - Reserve `panic!` for broken invariants, not invalid user input or provider
127
+ failure.
128
+ - Never discard a `Result` silently. If failure is intentionally ignored,
129
+ explain the safety argument in a nearby comment.
130
+
131
+ ## Control Flow
132
+
133
+ ### Early Returns and Pattern Matching
134
+
135
+ - Handle invalid or exceptional states first and keep the successful path at
136
+ the lowest indentation level.
137
+ - Prefer exhaustive `match` expressions when every variant carries meaningful
138
+ behavior.
139
+ - Use `if let` or `let ... else` for a single relevant pattern when the other
140
+ state exits or is intentionally ignored.
141
+ - Avoid wildcard arms when adding a new enum variant should force callers to
142
+ make a decision.
143
+
144
+ ### Iterators and Loops
145
+
146
+ - Use iterator adapters when they express a transformation clearly.
147
+ - Use a `for` loop when control flow, side effects, or error context becomes
148
+ clearer than a long adapter chain.
149
+ - Name closure parameters after the singular collection element; avoid opaque
150
+ one-letter names outside tiny mathematical scopes.
151
+ - Break complex iterator chains into typed intermediate values before the chain
152
+ becomes difficult to inspect or debug.
153
+
154
+ ## Concurrency and Async
155
+
156
+ - Do not hold a blocking or asynchronous lock across `.await` unless the lock
157
+ type and design explicitly support it.
158
+ - Every spawned task has an owner, completion strategy, and cancellation path.
159
+ - Propagate cancellation and timeout decisions from the caller rather than
160
+ hiding unbounded waits inside helpers.
161
+ - Use channels for ownership transfer and synchronization primitives for shared
162
+ state; do not rely on task scheduling order.
163
+ - Require `Send` and `Sync` only where the actual boundary needs them.
164
+
165
+ ## Unsafe Code
166
+
167
+ - Avoid `unsafe` when a safe abstraction can express the same contract.
168
+ - Every `unsafe` block has an adjacent `// SAFETY:` comment that states the
169
+ invariant making the operation sound.
170
+ - Every unsafe public function has a Rustdoc `# Safety` section describing the
171
+ caller's obligations.
172
+ - Keep unsafe code inside the smallest practical module and expose a safe API
173
+ around it.
174
+
175
+ ## Code Organization
176
+
177
+ - Keep public contracts discoverable before private implementation details.
178
+ - Separate parsing, validation, side effects, and presentation when they fail
179
+ for different reasons or require different tests.
180
+ - Extract nested calls into named values when doing so clarifies ownership,
181
+ error context, or side effects.
182
+ - Separate distinct operations with blank lines; keep comments attached to the
183
+ code whose intent they explain.
184
+ - Do not introduce macros for ordinary reuse. Use a macro when syntax-level
185
+ generation is genuinely the clearest contract, and document its accepted
186
+ forms and expansion assumptions.
187
+
188
+ ## Tests
189
+
190
+ - Unit tests live beside private implementation in `#[cfg(test)]` modules;
191
+ integration tests live in `tests/` and use the public API.
192
+ - Name tests after the behavior and condition being verified.
193
+ - Use table-like case arrays when several inputs share one contract, but keep
194
+ assertion failures readable for each case.
195
+ - Keep tests deterministic and isolated from the network, wall clock, and user
196
+ machine unless the suite explicitly provides those dependencies.
197
+ - Use temporary directories and fixtures with automatic cleanup.
198
+ - Test important errors and boundary conditions, not only the happy path.
199
+
200
+ ```rust
201
+ #[cfg(test)]
202
+ mod tests {
203
+ use super::{parse_mode, DeploymentEnvironment};
204
+
205
+ #[test]
206
+ fn parse_mode_accepts_production() {
207
+ let actual = parse_mode("production").expect("production is valid");
208
+
209
+ assert_eq!(actual, DeploymentEnvironment::Production);
210
+ }
211
+ }
212
+ ```
213
+
214
+ ## Verification
215
+
216
+ Run the project's configured commands. When working directly with a Rust
217
+ workspace, the minimum language checks are:
218
+
219
+ ```bash
220
+ cargo fmt --check
221
+ cargo check --all-targets
222
+ cargo clippy --all-targets --all-features -- -D warnings
223
+ cargo test --all-targets --all-features
224
+ ```
225
+
226
+ Use the repository's Nova scripts when they wrap these commands; do not bypass
227
+ additional project checks defined in `nova.config.json` or `package.json`.
@@ -5,7 +5,7 @@ Quotes: Double (only option). Indentation: 4-space. File naming: PascalCase + ro
5
5
  ## Documentation Style
6
6
 
7
7
  - Comment syntax: `///`
8
- - Padding tag: `- Since: 1.0.0` (DocC callout)
8
+ - Padding tag: `- Since: UNRELEASED` (DocC callout; Nova stamps it during the workspace release)
9
9
  - Param format: `- Parameter name: Name.` (description matches the parameter name, capitalized, with a trailing period)
10
10
  - Return format: `- Returns: Description.`
11
11
  - Throws format: `- Throws: Description.`
@@ -18,21 +18,21 @@ Quotes: Double (only option). Indentation: 4-space. File naming: PascalCase + ro
18
18
  ///
19
19
  /// Tunnel Store.
20
20
  ///
21
- /// - Since: 1.0.0
21
+ /// - Since: UNRELEASED
22
22
  ///
23
23
  @MainActor
24
24
  final class TunnelStore: ObservableObject {
25
25
  ///
26
26
  /// Tunnel Store - Managed Tunnels.
27
27
  ///
28
- /// - Since: 1.0.0
28
+ /// - Since: UNRELEASED
29
29
  ///
30
30
  @Published private(set) var managedTunnels: [Tunnel] = []
31
31
 
32
32
  ///
33
33
  /// Tunnel Store - Constructor.
34
34
  ///
35
- /// - Since: 1.0.0
35
+ /// - Since: UNRELEASED
36
36
  ///
37
37
  init() { ... }
38
38
 
@@ -41,14 +41,14 @@ final class TunnelStore: ObservableObject {
41
41
  ///
42
42
  /// - Parameter force: Force.
43
43
  ///
44
- /// - Since: 1.0.0
44
+ /// - Since: UNRELEASED
45
45
  ///
46
46
  func bootstrapIfNeeded(force: Bool = false) async { ... }
47
47
 
48
48
  ///
49
49
  /// Tunnel Store - Body.
50
50
  ///
51
- /// - Since: 1.0.0
51
+ /// - Since: UNRELEASED
52
52
  ///
53
53
  var body: some View { ... }
54
54
  }
@@ -56,13 +56,13 @@ final class TunnelStore: ObservableObject {
56
56
  ///
57
57
  /// Tunnel Status.
58
58
  ///
59
- /// - Since: 1.0.0
59
+ /// - Since: UNRELEASED
60
60
  ///
61
61
  enum TunnelStatus {
62
62
  ///
63
63
  /// Tunnel Status - Active.
64
64
  ///
65
- /// - Since: 1.0.0
65
+ /// - Since: UNRELEASED
66
66
  ///
67
67
  case active
68
68
  }
@@ -309,4 +309,4 @@ Don't inline complex expressions into string interpolation or other expressions.
309
309
 
310
310
  - **Creator** (function designer): may design a function to `throw` on failure — that's the API contract.
311
311
  - **Consumer** (function caller): always wraps calls to throwing functions in `do`/`try`/`catch`.
312
- - CLI entry points and `@main` never throw — handle errors and call `exit()` with the appropriate code.
312
+ - CLI entry points and `@main` never throw — handle errors and call `exit()` with the appropriate code.