@cbnventures/nova 0.35.0 → 0.37.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.
- package/bin/nova.mjs +17 -0
- package/build/package.json +3 -2
- package/build/scaffold-versions.json +54 -44
- package/build/src/cli/generate/github/workflows-blueprint-validate.d.ts +2 -2
- package/build/src/cli/generate/github/workflows-blueprint-validate.d.ts.map +1 -1
- package/build/src/cli/generate/github/workflows-blueprint-validate.js +116 -3
- package/build/src/cli/generate/github/workflows-blueprint-validate.js.map +1 -1
- package/build/src/cli/generate/github/workflows-blueprint.d.ts +11 -5
- package/build/src/cli/generate/github/workflows-blueprint.d.ts.map +1 -1
- package/build/src/cli/generate/github/workflows-blueprint.js +411 -35
- package/build/src/cli/generate/github/workflows-blueprint.js.map +1 -1
- package/build/src/cli/generate/must-haves/agent-conventions.d.ts.map +1 -1
- package/build/src/cli/generate/must-haves/agent-conventions.js +3 -0
- package/build/src/cli/generate/must-haves/agent-conventions.js.map +1 -1
- package/build/src/cli/generate/must-haves/dotenv.d.ts.map +1 -1
- package/build/src/cli/generate/must-haves/dotenv.js +1 -0
- package/build/src/cli/generate/must-haves/dotenv.js.map +1 -1
- package/build/src/cli/scaffold/app/astro.d.ts.map +1 -1
- package/build/src/cli/scaffold/app/astro.js +0 -1
- package/build/src/cli/scaffold/app/astro.js.map +1 -1
- package/build/src/cli/scaffold/app/vite.d.ts.map +1 -1
- package/build/src/cli/scaffold/app/vite.js +0 -1
- package/build/src/cli/scaffold/app/vite.js.map +1 -1
- package/build/src/cli/scaffold/docs/docusaurus.d.ts.map +1 -1
- package/build/src/cli/scaffold/docs/docusaurus.js +0 -1
- package/build/src/cli/scaffold/docs/docusaurus.js.map +1 -1
- package/build/src/cli/utility/changelog.d.ts.map +1 -1
- package/build/src/cli/utility/changelog.js +119 -67
- package/build/src/cli/utility/changelog.js.map +1 -1
- package/build/src/cli/utility/configure.d.ts.map +1 -1
- package/build/src/cli/utility/configure.js +126 -1
- package/build/src/cli/utility/configure.js.map +1 -1
- package/build/src/lib/corepack.d.ts +2 -2
- package/build/src/lib/corepack.d.ts.map +1 -1
- package/build/src/lib/corepack.js +16 -6
- package/build/src/lib/corepack.js.map +1 -1
- package/build/src/lib/docker-packaging.d.ts.map +1 -1
- package/build/src/lib/docker-packaging.js +15 -12
- package/build/src/lib/docker-packaging.js.map +1 -1
- package/build/src/lib/dotenv.d.ts.map +1 -1
- package/build/src/lib/dotenv.js +17 -8
- package/build/src/lib/dotenv.js.map +1 -1
- package/build/src/lib/env-managed-set.d.ts.map +1 -1
- package/build/src/lib/env-managed-set.js +55 -11
- package/build/src/lib/env-managed-set.js.map +1 -1
- package/build/src/lib/env-namespace.d.ts.map +1 -1
- package/build/src/lib/env-namespace.js +1 -0
- package/build/src/lib/env-namespace.js.map +1 -1
- package/build/src/lib/env-profiles.d.ts +3 -0
- package/build/src/lib/env-profiles.d.ts.map +1 -0
- package/build/src/lib/env-profiles.js +70 -0
- package/build/src/lib/env-profiles.js.map +1 -0
- package/build/src/lib/env-status.d.ts.map +1 -1
- package/build/src/lib/env-status.js +23 -2
- package/build/src/lib/env-status.js.map +1 -1
- package/build/src/lib/item.d.ts.map +1 -1
- package/build/src/lib/item.js +20 -3
- package/build/src/lib/item.js.map +1 -1
- package/build/src/lib/nova-config.d.ts.map +1 -1
- package/build/src/lib/nova-config.js +31 -0
- package/build/src/lib/nova-config.js.map +1 -1
- package/build/src/lib/regex.d.ts +7 -1
- package/build/src/lib/regex.d.ts.map +1 -1
- package/build/src/lib/regex.js +7 -1
- package/build/src/lib/regex.js.map +1 -1
- package/build/src/lib/run-scripts.d.ts.map +1 -1
- package/build/src/lib/run-scripts.js +24 -0
- package/build/src/lib/run-scripts.js.map +1 -1
- package/build/src/lib/scaffold.d.ts.map +1 -1
- package/build/src/lib/scaffold.js +7 -0
- package/build/src/lib/scaffold.js.map +1 -1
- package/build/src/lib/workflow-templates.js +4 -4
- package/build/src/lib/workflow-templates.js.map +1 -1
- package/build/src/types/cli/generate/github/workflows-blueprint-validate.d.ts +42 -4
- package/build/src/types/cli/generate/github/workflows-blueprint.d.ts +193 -17
- package/build/src/types/cli/utility/changelog.d.ts +49 -6
- package/build/src/types/cli/utility/configure.d.ts +52 -0
- package/build/src/types/lib/corepack.d.ts +13 -0
- package/build/src/types/lib/docker-packaging.d.ts +2 -0
- package/build/src/types/lib/dotenv.d.ts +10 -3
- package/build/src/types/lib/env-managed-set.d.ts +15 -0
- package/build/src/types/lib/env-namespace.d.ts +5 -0
- package/build/src/types/lib/env-profiles.d.ts +67 -0
- package/build/src/types/lib/env-status.d.ts +9 -0
- package/build/src/types/lib/item.d.ts +20 -3
- package/build/src/types/lib/nova-config.d.ts +14 -0
- package/build/src/types/lib/regex.d.ts +0 -2
- package/build/src/types/lib/run-scripts.d.ts +16 -0
- package/build/src/types/lib/scaffold.d.ts +8 -0
- package/build/src/types/shared.d.ts +47 -6
- package/build/src/types/tests/cli/generate/github/workflows-blueprint-publish-parity.test.d.ts +20 -0
- package/build/src/types/tests/cli/generate/github/workflows-blueprint-validate.test.d.ts +22 -0
- package/build/src/types/tests/cli/generate/github/workflows-blueprint.test.d.ts +16 -0
- package/build/src/types/tests/cli/generate/must-haves/agent-conventions.test.d.ts +40 -0
- package/build/src/types/tests/cli/utility/changelog.test.d.ts +48 -45
- package/build/src/types/tests/cli/utility/configure.test.d.ts +1 -0
- package/build/src/types/tests/cli/utility/run-scripts.test.d.ts +29 -0
- package/build/src/types/tests/lib/docker-packaging.test.d.ts +14 -0
- package/build/src/types/tests/lib/env-profiles.test.d.ts +20 -0
- package/build/templates/generators/must-haves/agent-conventions/AGENTS.md +8 -5
- package/build/templates/generators/must-haves/agent-conventions/CLAUDE.md +8 -5
- package/build/templates/generators/must-haves/agent-conventions/conventions/csharp.md +6 -6
- package/build/templates/generators/must-haves/agent-conventions/conventions/go.md +241 -0
- package/build/templates/generators/must-haves/agent-conventions/conventions/nova.md +155 -0
- package/build/templates/generators/must-haves/agent-conventions/conventions/python.md +7 -7
- package/build/templates/generators/must-haves/agent-conventions/conventions/rust.md +227 -0
- package/build/templates/generators/must-haves/agent-conventions/conventions/swift.md +9 -9
- package/build/templates/generators/must-haves/agent-conventions/conventions/typescript.md +145 -23
- package/build/templates/generators/must-haves/agent-conventions/conventions/universal.md +112 -103
- package/build/templates/generators/must-haves/ignore-files/gitignore +1 -0
- package/build/templates/scaffold/app/android/package.json +1 -1
- package/build/templates/scaffold/app/apple/Sources/App.swift +15 -2
- package/build/templates/scaffold/app/apple/Tests/AppTests.swift +14 -2
- package/build/templates/scaffold/app/apple/package.json +1 -1
- package/build/templates/scaffold/app/apple/project.yml +1 -0
- package/build/templates/scaffold/app/astro/package.json +1 -1
- package/build/templates/scaffold/app/discord-bot/package.json +1 -1
- package/build/templates/scaffold/app/express/package.json +1 -1
- package/build/templates/scaffold/app/nextjs/package.json +1 -1
- package/build/templates/scaffold/app/vite/package.json +2 -2
- package/build/templates/scaffold/app/vite/vite.config.mts +3 -0
- package/build/templates/scaffold/docs/docusaurus/package.json +4 -4
- package/build/templates/scaffold/docs/docusaurus/static/images/nova.svg +13 -5
- package/build/templates/scaffold/docs/docusaurus/vitest.config.mts +9 -0
- package/build/templates/scaffold/package/github-action/package.json +1 -1
- package/build/templates/scaffold/package/homebridge/package.json +1 -1
- package/build/templates/scaffold/package/pfsense/package.json +1 -1
- package/build/templates/scaffold/package/pfsense/port/files/usr/local/pkg/[__WORKSPACE_NAME__].inc +10 -0
- package/build/templates/scaffold/package/pfsense-root/.github/workflows/pfsense-[__WORKSPACE_NAME__].yml +62 -0
- package/build/templates/scaffold-options/app/android-native/.gitattributes +2 -0
- package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/MainActivity.kt +16 -2
- package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/NavigationKeys.kt +7 -1
- package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/data/DataRepository.kt +28 -4
- package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/theme/Color.kt +40 -6
- package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/theme/Theme.kt +22 -1
- package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/theme/Type.kt +8 -2
- package/build/templates/scaffold-options/app/android-native/app/src/main/java/[__ANDROID_PACKAGE_PATH__]/ui/main/MainScreenViewModel.kt +42 -6
- package/build/templates/scaffold-options/app/android-native/app/src/test/java/[__ANDROID_PACKAGE_PATH__]/ui/main/MainScreenViewModelTest.kt +31 -4
- package/build/templates/scaffold-options/app/android-native/gradle/wrapper/gradle-wrapper.jar +0 -0
- package/build/templates/scaffold-options/app/android-native/gradlew +189 -113
- package/build/templates/scaffold-options/app/android-native/gradlew.bat +79 -51
- package/build/templates/scaffold-options/app/astro/cloudflare/public/.assetsignore +15 -0
- package/build/templates/scaffold-options/app/web-launchpad/public/favicon.svg +13 -5
- package/build/templates/scaffold-options/docker-image/common/dockerignore +2 -0
- package/build/templates/scaffold-options/tool/serverless/cloudflare-workers/package.json +1 -1
- package/build/templates/scaffold-options/tool/serverless/vercel-functions/package.json +1 -1
- package/package.json +3 -2
|
@@ -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: `
|
|
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
|
-
|
|
22
|
-
|
|
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
|
-
|
|
33
|
-
|
|
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
|
-
|
|
48
|
-
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
59
|
+
/// - Since: UNRELEASED
|
|
60
60
|
///
|
|
61
61
|
enum TunnelStatus {
|
|
62
62
|
///
|
|
63
63
|
/// Tunnel Status - Active.
|
|
64
64
|
///
|
|
65
|
-
/// - Since:
|
|
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.
|