diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 5a92c3a..6e96f87 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -24,7 +24,7 @@ document of a type. `Primary File` may contain a glob (e.g. | DCD | Design Class Diagram | docs/dcd.md | 004 | | DICT | Domain Dictionary (PO and IT terms) | docs/dictionary.md | 002 | | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 029 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 030 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | ## Languages diff --git a/docs/business-case.md b/docs/business-case.md index f0b1237..edd0144 100644 --- a/docs/business-case.md +++ b/docs/business-case.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Objectives 2, 5 and 10, two scope items and success criterion 10: the AGPL-3.0 default needs GitHub and a public project; the framework's own submodules (qc) are fetched | [1cd27f7] | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Added objective 11 (global command, project created in the current folder), a scope item and success criterion 11 | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Objective 11, scope item and criterion 11: the configuration files default to the working folder's, then the checkout's | pending | --- @@ -44,7 +44,7 @@ One repeatable, reviewed procedure gives every new project the same secure basel 8. Let the Maintainer preset the project details in `config.env`, so that a detail that is set there is not asked again. 9. Ask for a credential that is not provided in `.env` (`GITEA_TOKEN`, `GITHUB_PAT`, `GITHUB_USER`) and, when the Maintainer agrees, create a `.env` file with the credentials the new project needs. 10. Let the Maintainer set the project's license in `config.env` (`PROJECT_LICENSE`), independent of the GitHub choice, or set `none` for no license. -11. Let the Maintainer start the script by name from the folder where the project is to be created, through a command link in a folder on `PATH`. +11. Let the Maintainer start the script by name from the folder where the project is to be created, through a command link in a folder on `PATH`, using the `config.env` and `.env` in that folder, or the checkout's when it has none. ## Scope @@ -58,7 +58,7 @@ One repeatable, reviewed procedure gives every new project the same secure basel - Asking for a credential that `.env` does not provide, and creating the new project's own `.env` (owner-only, ignored by git, never overwritten without a yes). - A project license set in `config.env` (`PROJECT_LICENSE`, optional, never asked), checked against the licenses the Gitea server offers. - Partial-failure reporting with a documented way to continue. -- Starting through a command link: the script finds its own files from the link, and the new project lands in the folder it was started in. +- Starting through a command link: the script finds its own files from the link, the new project lands in the folder it was started in, and `./config.env` and `./.env` there are read before the checkout's (confirmed before the first request). - Fetching the framework's own submodules (`git submodule update --init --recursive`), so the `qc` checklists are present. - Documentation of the SSH prerequisite for the submodule (Gitea SSH on port `10022`). @@ -101,7 +101,7 @@ Supports developing on self-hosted Gitea while publishing to GitHub, and adoptin | 8 | Preset details | A project detail set in `config.env` is never asked; an invalid one stops the run before any request and names the key | Tests with each key set, absent, empty and invalid | | 9 | Credentials asked and kept | A credential missing from `.env` is asked (not echoed) instead of stopping the run; the new project's `.env` is created only after a yes, owner-only, ignored by git, holding only the keys the project needs, and an existing `.env` is never replaced without a yes | Tests: each credential present and missing, `.env` written, declined, existing, file mode, git exclusion, no token in output | | 10 | Project license | `PROJECT_LICENSE` set: that license is on the Gitea repository with and without GitHub; `none`: no license; absent: AGPL-3.0 only when GitHub is chosen and the project is public; a license the server does not offer stops the run before anything is created | Tests with a license set, `none`, absent and not offered | -| 11 | Global command | Started through a command link in a `PATH` folder from another folder, the script runs, reads the checkout's `config.env` and `.env` and creates the project under that folder | Test run through a link; the README example run once | +| 11 | Global command | Started through a command link in a `PATH` folder from another folder, the script runs, reads `./config.env` and `./.env` of that folder, else the checkout's, names them before any request, and creates the project under that folder | Test run through a link with files in the folder, in the checkout and in neither; the README example run once | ## Risks diff --git a/docs/dcd.md b/docs/dcd.md index ec085d1..75abd01 100644 --- a/docs/dcd.md +++ b/docs/dcd.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-06 | Proposed | Jens Tirsvad Nielsen | S02 | ProjectRequest carries the license that applies (from DCD-001) | [d773fa9] | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Added Launcher, Checkout and WorkingFolder; startProjectCreation takes the checkout and working folder (from DCD-003, UC-002) | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Default configuration files: --config and --env, else ./config.env and ./.env in the working folder, else the checkout's | pending | --- @@ -33,7 +33,7 @@ enum Visibility { } class ProjectCreator <> { - +startProjectCreation(checkout : Checkout, workingFolder : WorkingFolder, configPath : Path [0..1], envPath : Path [0..1]) : PromptSet + +startProjectCreation(workingFolder : WorkingFolder, configFiles : ConfigFiles) : PromptSet +provideProjectDetails(name : String, description : String, visibility : Visibility, giteaOwner : Owner, githubOwner : Owner [0..1], directory : Path, enablePlanGate : Boolean, writeEnvFile : Boolean) : Summary } class ConfigLoader { @@ -83,6 +83,7 @@ class SummaryReport { class Launcher { +resolveCheckout(invocation : Path) : Checkout +currentFolder() : WorkingFolder + +locateConfigFiles(configPath : Path [0..1], envPath : Path [0..1], checkout : Checkout, workingFolder : WorkingFolder) : ConfigFiles +startFromWorkingFolder(configPath : Path [0..1], envPath : Path [0..1]) : PromptSet } class Checkout { @@ -92,6 +93,12 @@ class Checkout { } class WorkingFolder { -path : Path + +configFile() : Path [0..1] + +envFile() : Path [0..1] +} +class ConfigFiles { + -configFile : Path + -envFile : Path } class Run { -isApply : Boolean @@ -186,6 +193,8 @@ class Summary { Launcher "1" --> "1" ProjectCreator : starts Launcher ..> Checkout : creates Launcher ..> WorkingFolder : creates +Launcher ..> ConfigFiles : creates +Run "1" *-- "1" ConfigFiles Run "1" *-- "1" Checkout Run "1" *-- "1" WorkingFolder ProjectCreator ..> ConfigLoader : creates @@ -249,9 +258,10 @@ Repository "0..*" --> "1" Visibility | Class | Refines (Domain Model concept) | Responsibility | Attributes | Operations | | --- | --- | --- | --- | --- | -| `Launcher` | Command Link (the object that follows it) | Follows the command link to the checkout, takes the folder the Maintainer stands in, and starts the run. | none | `resolveCheckout`, `currentFolder`, `startFromWorkingFolder` | +| `Launcher` | Command Link (the object that follows it) | Follows the command link to the checkout, takes the folder the Maintainer stands in, chooses the two configuration files, and starts the run. | none | `resolveCheckout`, `currentFolder`, `locateConfigFiles`, `startFromWorkingFolder` | | `Checkout` | Checkout | Names the folder that holds the script's own files and the default `config.env` and `.env`. | `path` | `configFile`, `envFile` | -| `WorkingFolder` | Working Folder | Names the base of the default directory of the new project. | `path` | none | +| `WorkingFolder` | Working Folder | Names the base of the default directory of the new project and the files it may hold. | `path` | `configFile`, `envFile` | +| `ConfigFiles` | none (system concept of [OC-002]) | Carries the two files chosen for the `Configuration`. | `configFile`, `envFile` | none | | `ProjectCreator` | none (controller for the system operations of [OC-001]) | Receives the two system operations, sequences the steps and stops on the first failure. | none | `startProjectCreation`, `provideProjectDetails` | | `ConfigLoader` | Configuration | Reads `config.env` and `.env` as plain text and validates every value, preset project details included. | none | `load` | | `CredentialCollector` | none (system concept) | Asks, without echo, for a credential that `.env` does not provide and validates it like one read from `.env`. | none | `collect` | @@ -291,9 +301,10 @@ Repository "0..*" --> "1" Visibility | Method signature | Operation Contract / SD message | | --- | --- | -| `ProjectCreator.startProjectCreation(checkout, workingFolder, configPath, envPath) : PromptSet` | [OC-001] `startProjectCreation`; [SD-001] `startProjectCreation()`; [SD-002] `startProjectCreation(checkout, workingFolder, ...)` | +| `ProjectCreator.startProjectCreation(workingFolder, configFiles) : PromptSet` | [OC-001] `startProjectCreation`; [SD-001] `startProjectCreation()`; [SD-002] `startProjectCreation(checkout, workingFolder, ...)` | | `Launcher.startFromWorkingFolder(configPath, envPath) : PromptSet` | [OC-002] `startFromWorkingFolder`; [SD-002] | | `Launcher.resolveCheckout(invocation) : Checkout`, `Launcher.currentFolder() : WorkingFolder` | [OC-002] P2, P3; [SD-002] | +| `Launcher.locateConfigFiles(configPath, envPath, checkout, workingFolder) : ConfigFiles`, `WorkingFolder.configFile()`, `WorkingFolder.envFile()` | [OC-002] P5; [SD-002] `locateConfigFiles(...)` | | `ProjectCreator.provideProjectDetails(name, description, visibility, giteaOwner, githubOwner, directory, enablePlanGate, writeEnvFile) : Summary` | [OC-001] `provideProjectDetails`; [SD-001] `provideProjectDetails(...)` | | `ConfigLoader.load(configFile, envFile) : Configuration` | [SD-001] `load(config.env, .env)`; [OC-001] `startProjectCreation` P2 | | `CredentialCollector.collect(configuration, kinds) : Configuration` | [SD-001] `collect(configuration, GITEA_TOKEN)` and `collect(configuration, GITHUB_PAT, GITHUB_USER)`; [OC-001] `startProjectCreation` P2 and the precondition of `provideProjectDetails` | @@ -362,5 +373,4 @@ SOLID check: no class has more than one reason to change (one host API, one kind [SD-001]: ./uc-001/sd.md [MIL-005]: ./milestones/mil-005-credentials.md [DICT-001]: ./dictionary.md -[d773fa9]: https://git.tirsystem.com/TirSystem-BashScript/repo_foundry/commit/d773fa91df5a54090254e12e074880fb6526a9ff [1cd27f7]: https://git.tirsystem.com/TirSystem-BashScript/repo_foundry/commit/1cd27f77ed844773a969210a11de0d8bb98ac98f diff --git a/docs/dictionary.md b/docs/dictionary.md index d54e024..6381675 100644 --- a/docs/dictionary.md +++ b/docs/dictionary.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-06 | Proposed | Jens Tirsvad Nielsen | S02 | LicenseFile definition no longer tied to GitHub | [d773fa9] | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Added Command Link, Checkout and Working Folder (DM-003, UC-002) | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | `ConfigFiles` named as a system concept without a PO term | pending | --- @@ -49,8 +49,9 @@ Maps each Product Owner (PO) term to its professional IT term. PO language: Engl - The Domain Model, use cases and user stories use the PO term; the Operation Contract, Sequence Diagram, Design Class Diagram and ERD use the IT term. - One IT term per PO term and one PO term per IT term; no synonyms. -- `Run`, `ToolCheck`, `PreflightResult` and `PromptSet` appear in [OC-001] but - have no PO term: they are system concepts, not domain concepts, and are not +- `Run`, `ToolCheck`, `PreflightResult`, `PromptSet` and `ConfigFiles` (the two + files chosen for the Configuration, in [OC-002]) appear in the Operation + Contracts but have no PO term: they are system concepts, not domain concepts, and are not in the Domain Model. - `InstallResult` and the enumeration `Visibility` appear only in [DCD-001]: `InstallResult` carries the three results of one operation, and `Visibility` @@ -67,5 +68,4 @@ Maps each Product Owner (PO) term to its professional IT term. PO language: Engl [DM-002]: ./domain-model.md [OC-001]: ./uc-001/oc.md [DCD-001]: ./uc-001/dcd.md -[d773fa9]: https://git.tirsystem.com/TirSystem-BashScript/repo_foundry/commit/d773fa91df5a54090254e12e074880fb6526a9ff [1cd27f7]: https://git.tirsystem.com/TirSystem-BashScript/repo_foundry/commit/1cd27f77ed844773a969210a11de0d8bb98ac98f diff --git a/docs/domain-model.md b/docs/domain-model.md index 73c57d7..38d7802 100644 --- a/docs/domain-model.md +++ b/docs/domain-model.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | License: the AGPL-3.0 default needs GitHub and a public project | [1cd27f7] | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Added Command Link, Checkout and Working Folder (from DM-003, UC-002) | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Default configuration files: --config and --env, else ./config.env and ./.env in the working folder, else the checkout's | pending | --- @@ -128,6 +128,7 @@ Maintainer "1" --> "0..*" CommandLink : makes CommandLink "0..*" --> "1" Checkout : leads to Maintainer "1" --> "1" WorkingFolder : starts the script in Checkout "1" --> "1" Configuration : holds by default +WorkingFolder "1" --> "0..1" Configuration : may hold WorkingFolder "1" --> "0..*" LocalProject : is the base of @enduml ``` @@ -155,7 +156,7 @@ WorkingFolder "1" --> "0..*" LocalProject : is the base of | Credentials File | The file in a Local Project that holds a copy of the Access Tokens (and the GitHub account name) the project needs; readable by its owner only and ignored by git | address | [UC-001] step 9 "credentials file" | | Command Link | A name in a folder on the shell's search path that leads to the script in the Checkout | name, folder | [UC-002] step 1 "command link" | | Checkout | The folder that holds RepoFoundry: the script, its own files and by default `config.env` and `.env` | path | [UC-002] step 4 "checkout" | -| Working Folder | The folder in which the Maintainer starts the script and under which the new project is created by default | path | [UC-002] step 2 "working folder" | +| Working Folder | The folder in which the Maintainer starts the script, under which the new project is created by default, and which may hold its own `config.env` and `.env` | path | [UC-002] step 2 "working folder" | | Summary | The report of what was created, skipped or failed and how to continue | created items, skipped items, next steps | [UC-001] step 10 "summary" | ## Association Table @@ -189,6 +190,7 @@ WorkingFolder "1" --> "0..*" LocalProject : is the base of | Command Link | leads to | Checkout | 0..* to 1 | | Maintainer | starts the script in | Working Folder | 1 to 1 | | Checkout | holds by default | Configuration | 1 to 1 | +| Working Folder | may hold | Configuration | 1 to 0..1 | | Working Folder | is the base of | Local Project | 1 to 0..* | ## Generalizations diff --git a/docs/milestones/mil-007-framework-checklists.md b/docs/milestones/mil-007-framework-checklists.md index ca6fb5a..cbe054c 100644 --- a/docs/milestones/mil-007-framework-checklists.md +++ b/docs/milestones/mil-007-framework-checklists.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Added UC-002 and US-002 (global command); tasks 2 and 3 trace to UC-002 | [1cd27f7] | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Task 4 renamed so its issue title is unique (the sync matches issues by title) | [be759e3] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | The configuration files default to the working folder's, then the checkout's, confirmed and named (deliverable 3, criteria 9 and 10, tasks 2 to 4) | pending | --- @@ -22,7 +22,7 @@ Decide whether a new project holds the whole framework, including the `qc` check 1. `create-project.sh` that, after adding the `framework` submodule (and when `framework` already exists as that submodule), runs `git submodule update --init --recursive` in the new project, so `framework/qc/` holds the checklists. 2. `create-project.sh` that finds its own files when started through a symlink, so a link in a folder on `PATH` works from any directory. -3. A README usage section that says: run the script from the folder in which the project is to be created (the default directory is `./` relative to where it is started), keep `config.env` and `.env` in the checkout and point to them with `--config` and `--env` or place them where the script reads them, and make the script global with a worked example (a symlink in a `PATH` folder, with the check that it works), for Linux, macOS and Git Bash on Windows. +3. A README usage section that says: run the script from the folder in which the project is to be created (the default directory is `./` relative to where it is started), keep `config.env` and `.env` in the folder where the project is created or in the checkout (the folder's file wins, each file on its own), name other files with `--config` and `--env`, and make the script global with a worked example (a symlink in a `PATH` folder, with the check that it works), for Linux, macOS and Git Bash on Windows. ## Go / No-Go Criteria @@ -36,6 +36,8 @@ Decide whether a new project holds the whole framework, including the `qc` check | 6 | The README example for the global command was run once as written and its check passed | Verified | An example that was not run | | 7 | The README states the folder to start from and where the new project lands, with an example from a folder that is not the checkout | Reviewed by S02 | Missing or unclear | | 8 | All acceptance criteria of US-001.07 and US-002 in [US-001] are met | Verified | Any unmet | +| 9 | With `--config` and `--env` absent, `./config.env` and `./.env` in the working folder are used, each file on its own, and the checkout's stand in for a missing one; with neither present the run stops before any request and names both places | Tests pass | A file used from another place, or a request made | +| 10 | A file from the working folder is named with the Gitea address it holds and needs a yes, default no, before the first request; every file used is named in the output | Tests pass | A request before the yes, or a file used without being named | ## Dependencies @@ -68,9 +70,9 @@ Decide whether a new project holds the whole framework, including the `qc` check | # | Task | Summary | Needs its own Use Case/User Story? | Reference | | --- | --- | --- | --- | --- | | 1 | Fetch the framework's own submodules | After `git submodule add` of the framework, and on the "already a submodule" path, run `git submodule update --init --recursive` in the new project. A failure stops the step, reports what exists and names the command to run by hand, without a credential. Step 9 and extension 9e of [UC-001]. | Yes | [UC-001] | -| 2 | Start through a command link | Resolve `BASH_SOURCE` through links (without requiring `readlink -f`, which macOS lacks) so `SCRIPT_DIR` and `PROJECT_ROOT` point into the checkout, and keep the current folder as the base of the default directory. Errors name the folder or path looked in. Steps 3 to 6 and extensions 4a and 4b of [UC-002]. | Yes | [UC-002] | -| 3 | Document the usage | Step 1 and extensions 1a and 3a of [UC-002]. README usage section: start from the folder where the project is to be created, where `config.env` and `.env` are read from, `--config` and `--env`, and the global command with a worked example and its check, for Linux, macOS and Git Bash on Windows. | Yes | [UC-002] | -| 4 | Test the qc fetch and the command link | `qc` filled after a run and after a rerun, nested fetch failure, framework without a submodule, start through a symlink from another folder. | No | | +| 2 | Start through a command link | Resolve `BASH_SOURCE` through links (without requiring `readlink -f`, which macOS lacks) so `SCRIPT_DIR` and `PROJECT_ROOT` point into the checkout, keep the current folder as the base of the default directory, and choose `config.env` and `.env` (named, else `./`, else the checkout's), naming them and asking a yes for a file from the working folder. Errors name the places looked in. Steps 3 to 6 and extensions 4a to 4c of [UC-002]. | Yes | [UC-002] | +| 3 | Document the usage | Step 1 and extensions 1a and 3a of [UC-002]. README usage section: start from the folder where the project is to be created, where `config.env` and `.env` are read from (the folder first, then the checkout), the confirmation of a file from the folder, `--config` and `--env`, and the global command with a worked example and its check, for Linux, macOS and Git Bash on Windows. | Yes | [UC-002] | +| 4 | Test the qc fetch and the command link | `qc` filled after a run and after a rerun, nested fetch failure, framework without a submodule, start through a symlink from another folder; configuration files named, in the folder, in the checkout, mixed and in neither; the confirmation answered yes and no. | No | | --- @@ -79,5 +81,4 @@ Decide whether a new project holds the whole framework, including the `qc` check [UC-001]: ../uc-001/uc.md [UC-002]: ../uc-002/uc.md [MIL-003]: ./mil-003-scaffold-and-release.md -[1cd27f7]: https://git.tirsystem.com/TirSystem-BashScript/repo_foundry/commit/1cd27f77ed844773a969210a11de0d8bb98ac98f [be759e3]: https://git.tirsystem.com/TirSystem-BashScript/repo_foundry/commit/be759e38326eac2b11e65a2b582b2431186e338b diff --git a/docs/sqa/reviews/rc-029-default-config-files.md b/docs/sqa/reviews/rc-029-default-config-files.md new file mode 100644 index 0000000..7ad067b --- /dev/null +++ b/docs/sqa/reviews/rc-029-default-config-files.md @@ -0,0 +1,82 @@ +# SQA Review Record: Default configuration files from the working folder + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-029 | +| CrossReference | [MIL-007], [QC-MIL-001], [UC-002], [BC-001], [US-001], [DM-003], [DM-002], [OC-002], [SD-002], [DCD-003], [DCD-002], [DICT-001], [SSD-002] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: the change that makes `./config.env` and `./.env` in the working folder the default configuration files (after `--config` and `--env`, before the checkout's). It touches [MIL-007] and, through it, [BC-001], [US-001], [UC-002], [SSD-002], [DM-003], [DM-002], [OC-002], [SD-002], [DCD-003], [DCD-002] and [DICT-001]. It follows [RC-022] to [RC-028], which reviewed the first version of these documents; where this record disagrees with them, this record applies. +- Checklist used: [QC-MIL-001] for [MIL-007]; the checklists of the other types are applied to the changed parts below. +- Review date: 2026-10-07 + +## Checklist Results ([MIL-007], QC-MIL-001) + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | A concrete deliverable is defined for every gate | Pass | Deliverable 3 now names the folder-first lookup; the code and tests are named in tasks 2 and 4. | +| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Criteria 9 and 10 are new and objective: which file is used, that nothing is requested before the yes, and that every file used is named. | +| 3 | Dependencies on other milestones are explicitly mapped | Pass | Unchanged: [MIL-003]. | +| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Objective 11 and success criterion 11 of [BC-001] now carry the lookup rule. | +| 5 | Milestone owner and approving reviewer are identified | Pass | Unchanged: S01 and S02. | +| 6 | Milestone has a defined target date consistent with project constraints | Pass | Unchanged: 2026-12-11. | + +## Change checks on the other artifacts + +| Artifact | Change | Status | Evidence/Notes | +| --- | --- | --- | --- | +| [UC-002] | Precondition, step 4, extensions 4b and 4c, and two rules | Pass | Each file is chosen on its own: named, else `./`, else the checkout's. Extension 4c asks for a yes (default no) before the first request. The use case stays free of implementation detail. | +| [SSD-002] | One sentence: the confirmation is out of scope | Pass | Same convention as the consent questions of [SSD-001]. | +| [DM-003], [DM-002] | Association Working Folder "may hold" Configuration, 1 to 0..1; Working Folder definition | Pass | Both models changed in the same way; multiplicity on both ends. | +| [OC-002] | `ConfigFiles` and a new P5; former P5 and P6 become P6 and P7; two exceptions | Pass | Declarative: the chosen paths are stated as values, not as a search procedure. Each exception names its failing precondition. | +| [SD-002] | `locateConfigFiles`, creation of `ConfigFiles`, a confirmation `alt`, a new signature of `startProjectCreation` | Pass | Every postcondition has a message in the coverage table; `create` is shown for `ConfigFiles`. | +| [DCD-003], [DCD-002] | `ConfigFiles`; `Launcher.locateConfigFiles`; `WorkingFolder.configFile` and `envFile`; the signature of `startProjectCreation` | Pass with a note | Method Traceability covers each new method. The signature of `startProjectCreation` now differs more from [DCD-001], [OC-001] and [SD-001]; this widens the action item of [RC-028]. | +| [DICT-001] | `ConfigFiles` named as a system concept without a PO term | Pass | Treated like `Run` and `PromptSet`, as the dictionary rules allow. | +| [BC-001], [US-001] | Objective 11, scope item and criterion 11; the acceptance criteria of US-002 | Pass | Given/when/then; the confirmation and the naming of files are testable. | + +## Risk found in the change + +A `config.env` in the working folder can set `GITEA_URL` to another host, and the token from `.env` would then be sent there on the first request. That is why [UC-002] extension 4c and [MIL-007] criterion 10 require the files and the Gitea address to be named and a yes before any request. The yes does not protect a Maintainer who confirms without reading, and it adds one prompt to every run that uses a folder file; if S01 finds the prompt too heavy, the alternative is to confirm only when the address in the folder's `config.env` differs from the checkout's. + +## Overall Verdict + +Go-with-conditions — the change is consistent across the documents, and the security risk above is answered by a criterion that can be tested. The status stays `Proposed` until the action items are closed. Drafted by Claude Code for S02; the author and reviewer are the same person for now. The verdict takes effect only when S02 confirms it. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Decide whether the confirmation is asked on every run that uses a folder file, or only when the Gitea address differs from the checkout's | S01 | Before [MIL-007] starts | +| Settle the `startProjectCreation` signature in [OC-001], [SD-001] and [DCD-001], as in the action item of [RC-028] | S01 | Before [MIL-007] starts | + +--- + +[MIL-007]: ../../milestones/mil-007-framework-checklists.md +[QC-MIL-001]: ../../../framework/qc/qc-milestones-gateways.md +[UC-002]: ../../uc-002/uc.md +[BC-001]: ../../business-case.md +[US-001]: ../../user-stories.md +[DM-003]: ../../uc-002/dm.md +[DM-002]: ../../domain-model.md +[OC-002]: ../../uc-002/oc.md +[SD-002]: ../../uc-002/sd.md +[DCD-003]: ../../uc-002/dcd.md +[DCD-002]: ../../dcd.md +[DICT-001]: ../../dictionary.md +[SSD-002]: ../../uc-002/ssd.md +[SSD-001]: ../../uc-001/ssd.md +[OC-001]: ../../uc-001/oc.md +[SD-001]: ../../uc-001/sd.md +[DCD-001]: ../../uc-001/dcd.md +[RC-022]: ./rc-022-mil-007.md +[RC-028]: ./rc-028-dcd-003.md +[MIL-003]: ../../milestones/mil-003-scaffold-and-release.md diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index 5495783..5305856 100644 --- a/docs/sqa/traceability-matrix.md +++ b/docs/sqa/traceability-matrix.md @@ -24,7 +24,7 @@ updated whenever an artifact instance is created or reviewed. | Artifact Instance | Type | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) | | --- | --- | --- | --- | --- | -| [BC-001] | BC | - | [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [US-001], [UCD-001] | [RC-010], [RC-018], [RC-020], [RC-022] | +| [BC-001] | BC | - | [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [US-001], [UCD-001] | [RC-010], [RC-018], [RC-020], [RC-022], [RC-029] | | [SA-001] | SA | [BC-001] | [UCD-001], [UC-001], [DICT-001] | [RC-013] | | [PP-001] | PP | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007] | [RC-012], [RC-018], [RC-020], [RC-022] | | [MIL-001] | MIL | [BC-001], [PP-001] | [US-001] | [RC-011], [RC-016] | @@ -33,24 +33,24 @@ updated whenever an artifact instance is created or reviewed. | [MIL-004] | MIL | [BC-001], [PP-001] | [US-001] | [RC-018], [RC-019] | | [MIL-005] | MIL | [BC-001], [PP-001] | [US-001] | [RC-020] | | [MIL-006] | MIL | [BC-001], [PP-001] | [US-001] | [RC-022] | -| [MIL-007] | MIL | [BC-001], [PP-001] | [US-001], [UC-002] | [RC-022] | +| [MIL-007] | MIL | [BC-001], [PP-001] | [US-001], [UC-002] | [RC-022], [RC-029] | | [UCD-001] | UCD | [BC-001], [SA-001] | [US-001], [UC-001], [UC-002] | [RC-009], [RC-023] | -| [US-001] | US | [BC-001], [UCD-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007] | [UC-001] | [RC-001], [RC-020], [RC-022] | +| [US-001] | US | [BC-001], [UCD-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007] | [UC-001] | [RC-001], [RC-020], [RC-022], [RC-029] | | [UC-001] | UC | [UCD-001], [US-001], [SA-001] | [SSD-001], [DM-001] | [RC-002], [RC-020], [RC-023] | -| [UC-002] | UC | [UCD-001], [US-001], [SA-001], [BC-001] | [SSD-002], [DM-003] | [RC-023] | -| [SSD-002] | SSD | [UC-002], [DM-003] | [OC-002] | [RC-024] | -| [DM-003] | DM | [UC-002], [UCD-001], [SSD-002], [DICT-001], [DM-001] | [OC-002], [DCD-003] | [RC-025] | -| [OC-002] | OC | [SSD-002], [DM-003] | [SD-002] | [RC-026] | -| [SD-002] | SD | [OC-002], [DCD-003] | [DCD-003] | [RC-027] | -| [DCD-003] | DCD | [DM-003], [SD-002], [DICT-001], [UC-002], [DCD-001] | [DCD-002] | [RC-028] | +| [UC-002] | UC | [UCD-001], [US-001], [SA-001], [BC-001] | [SSD-002], [DM-003] | [RC-023], [RC-029] | +| [SSD-002] | SSD | [UC-002], [DM-003] | [OC-002] | [RC-024], [RC-029] | +| [DM-003] | DM | [UC-002], [UCD-001], [SSD-002], [DICT-001], [DM-001] | [OC-002], [DCD-003] | [RC-025], [RC-029] | +| [OC-002] | OC | [SSD-002], [DM-003] | [SD-002] | [RC-026], [RC-029] | +| [SD-002] | SD | [OC-002], [DCD-003] | [DCD-003] | [RC-027], [RC-029] | +| [DCD-003] | DCD | [DM-003], [SD-002], [DICT-001], [UC-002], [DCD-001] | [DCD-002] | [RC-028], [RC-029] | | [SSD-001] | SSD | [UC-001] | [OC-001] | [RC-003], [RC-020] | | [DM-001] | DM | [UC-001], [SSD-001] | [DM-002], [DICT-001], [OC-001], [DCD-001] | [RC-004], [RC-020] | -| [DM-002] | DM | [DM-001] | [DICT-001], [DCD-001], [DCD-002] | [RC-005], [RC-020], [RC-025] | -| [DICT-001] | DICT | [BC-001], [SA-001], [DM-001], [DM-002] | [OC-001], [SD-001] | [RC-008], [RC-020], [RC-025] | +| [DM-002] | DM | [DM-001] | [DICT-001], [DCD-001], [DCD-002] | [RC-005], [RC-020], [RC-025], [RC-029] | +| [DICT-001] | DICT | [BC-001], [SA-001], [DM-001], [DM-002] | [OC-001], [SD-001] | [RC-008], [RC-020], [RC-025], [RC-029] | | [OC-001] | OC | [SSD-001], [DM-001] | [SD-001] | [RC-006], [RC-020], [RC-026] | | [SD-001] | SD | [OC-001] | [DCD-001] | [RC-007], [RC-020], [RC-021] | | [DCD-001] | DCD | [UC-001], [DM-001], [DM-002], [OC-001], [SD-001], [DICT-001] | [DCD-002] | [RC-021] | -| [DCD-002] | DCD | [DCD-001], [DCD-003], [DM-002], [DICT-001] | - | [RC-021], [RC-028] | +| [DCD-002] | DCD | [DCD-001], [DCD-003], [DM-002], [DICT-001] | - | [RC-021], [RC-028], [RC-029] | ## Coverage Notes @@ -80,6 +80,7 @@ updated whenever an artifact instance is created or reviewed. [RC-026]: ./reviews/rc-026-oc-002.md [RC-027]: ./reviews/rc-027-sd-002.md [RC-028]: ./reviews/rc-028-dcd-003.md +[RC-029]: ./reviews/rc-029-default-config-files.md [DCD-001]: ../uc-001/dcd.md [DCD-002]: ../dcd.md [UCD-001]: ../use-case-diagram.md diff --git a/docs/uc-002/dcd.md b/docs/uc-002/dcd.md index f24dc71..476d78f 100644 --- a/docs/uc-002/dcd.md +++ b/docs/uc-002/dcd.md @@ -10,6 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Initial version | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Default configuration files: --config and --env, else ./config.env and ./.env in the working folder, else the checkout's | pending | --- @@ -24,6 +25,7 @@ Covers [UC-002]. Adds the classes that start the script through a command link. class Launcher { +resolveCheckout(invocation : Path) : Checkout +currentFolder() : WorkingFolder + +locateConfigFiles(configPath : Path [0..1], envPath : Path [0..1], checkout : Checkout, workingFolder : WorkingFolder) : ConfigFiles +startFromWorkingFolder(configPath : Path [0..1], envPath : Path [0..1]) : PromptSet } class Checkout { @@ -33,14 +35,22 @@ class Checkout { } class WorkingFolder { -path : Path + +configFile() : Path [0..1] + +envFile() : Path [0..1] +} +class ConfigFiles { + -configFile : Path + -envFile : Path } class ProjectCreator { - +startProjectCreation(checkout : Checkout, workingFolder : WorkingFolder, configPath : Path [0..1], envPath : Path [0..1]) : PromptSet + +startProjectCreation(workingFolder : WorkingFolder, configFiles : ConfigFiles) : PromptSet } class Run Launcher "1" --> "1" ProjectCreator : starts Launcher ..> Checkout : creates Launcher ..> WorkingFolder : creates +Launcher ..> ConfigFiles : creates +Run "1" *-- "1" ConfigFiles Run "1" *-- "1" Checkout Run "1" *-- "1" WorkingFolder @enduml @@ -50,9 +60,10 @@ Run "1" *-- "1" WorkingFolder | Class | Refines (Domain Model concept) | Responsibility | Attributes | Operations | | --- | --- | --- | --- | --- | -| `Launcher` | Command Link (the object that follows it) | Follows the command link to the checkout, takes the folder the Maintainer stands in, and starts the run. | none | `resolveCheckout`, `currentFolder`, `startFromWorkingFolder` | +| `Launcher` | Command Link (the object that follows it) | Follows the command link to the checkout, takes the folder the Maintainer stands in, chooses the two configuration files, and starts the run. | none | `resolveCheckout`, `currentFolder`, `locateConfigFiles`, `startFromWorkingFolder` | | `Checkout` | Checkout | Names the folder that holds the script's own files and the default `config.env` and `.env`. | `path` | `configFile`, `envFile` | -| `WorkingFolder` | Working Folder | Names the base of the default directory of the new project. | `path` | none | +| `WorkingFolder` | Working Folder | Names the base of the default directory of the new project and the files it may hold. | `path` | `configFile`, `envFile` | +| `ConfigFiles` | none (system concept of [OC-002]) | Carries the two files chosen for the `Configuration`. | `configFile`, `envFile` | none | The concept Command Link has no class: it is a link the Maintainer makes with the shell, and the system only follows it. @@ -63,8 +74,10 @@ The concept Command Link has no class: it is a link the Maintainer makes with th | `Launcher.startFromWorkingFolder(configPath, envPath) : PromptSet` | [SD-002] `startFromWorkingFolder`; P1, P6 | | `Launcher.resolveCheckout(invocation) : Checkout` | [SD-002] `resolveCheckout(invocation)`; P2 | | `Launcher.currentFolder() : WorkingFolder` | [SD-002] `currentFolder()`; P3 | -| `Checkout.configFile() : Path`, `Checkout.envFile() : Path` | [SD-002] `startProjectCreation`; P5 | -| `ProjectCreator.startProjectCreation(checkout, workingFolder, configPath, envPath) : PromptSet` | [SD-002] `startProjectCreation`; P4, P5, P6. Replaces the signature of [DCD-001] by adding `checkout`, `workingFolder`, `configPath` and `envPath` | +| `Launcher.locateConfigFiles(configPath, envPath, checkout, workingFolder) : ConfigFiles` | [SD-002] `locateConfigFiles(...)`; P5 | +| `WorkingFolder.configFile() : Path [0..1]`, `WorkingFolder.envFile() : Path [0..1]` | [SD-002] `locateConfigFiles`; P5 | +| `Checkout.configFile() : Path`, `Checkout.envFile() : Path` | [SD-002] `locateConfigFiles`; P5 | +| `ProjectCreator.startProjectCreation(workingFolder, configFiles) : PromptSet` | [SD-002] `startProjectCreation`; P4, P6, P7. Replaces the signature of [DCD-001] by adding `workingFolder` and `configFiles` | ## Pattern Annotations @@ -75,7 +88,7 @@ The concept Command Link has no class: it is a link the Maintainer makes with th ## Dependency Check -`Launcher` depends on `ProjectCreator`, `Checkout` and `WorkingFolder`; none of them depends on `Launcher`, so no cycle is added. +`Launcher` depends on `ProjectCreator`, `Checkout`, `WorkingFolder` and `ConfigFiles`; none of them depends on `Launcher`, so no cycle is added. --- diff --git a/docs/uc-002/dm.md b/docs/uc-002/dm.md index 4d0d5f3..2a603e3 100644 --- a/docs/uc-002/dm.md +++ b/docs/uc-002/dm.md @@ -10,6 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Initial version | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Default configuration files: --config and --env, else ./config.env and ./.env in the working folder, else the checkout's | pending | --- @@ -46,6 +47,7 @@ Maintainer "1" --> "0..*" CommandLink : makes CommandLink "0..*" --> "1" Checkout : leads to Maintainer "1" --> "1" WorkingFolder : starts the script in Checkout "1" --> "1" Configuration : holds by default +WorkingFolder "1" --> "0..1" Configuration : may hold WorkingFolder "1" --> "0..*" LocalProject : is the base of @enduml ``` @@ -56,7 +58,7 @@ WorkingFolder "1" --> "0..*" LocalProject : is the base of | --- | --- | --- | --- | | Command Link | A name in a folder on the shell's search path that leads to the script in the checkout | name, folder | [UC-002] step 1 "command link" | | Checkout | The folder that holds RepoFoundry: the script, its own files and by default `config.env` and `.env` | path | [UC-002] step 4 "checkout" | -| Working Folder | The folder in which the Maintainer starts the script and under which the new project is created by default | path | [UC-002] step 2 "working folder" | +| Working Folder | The folder in which the Maintainer starts the script, under which the new project is created by default, and which may hold its own `config.env` and `.env` | path | [UC-002] step 2 "working folder" | ## Association Table @@ -66,6 +68,7 @@ WorkingFolder "1" --> "0..*" LocalProject : is the base of | Command Link | leads to | Checkout | 0..* to 1 | | Maintainer | starts the script in | Working Folder | 1 to 1 | | Checkout | holds by default | Configuration | 1 to 1 | +| Working Folder | may hold | Configuration | 1 to 0..1 | | Working Folder | is the base of | Local Project | 1 to 0..* | ## Generalizations diff --git a/docs/uc-002/oc.md b/docs/uc-002/oc.md index c6c46c6..87e6793 100644 --- a/docs/uc-002/oc.md +++ b/docs/uc-002/oc.md @@ -10,10 +10,11 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Initial version | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Default configuration files: --config and --env, else ./config.env and ./.env in the working folder, else the checkout's | pending | --- -Concepts below use the IT terms of [DICT-001] for the PO concepts of [DM-003]. `Run` and `PromptSet` are the system concepts of [OC-001]. The operation `provideProjectDetails` is the one of [OC-001]; the only change is the base of its default `directory`, stated in P4. +Concepts below use the IT terms of [DICT-001] for the PO concepts of [DM-003]. `Run` and `PromptSet` are the system concepts of [OC-001]; `ConfigFiles` is a system concept of this contract: the two files chosen for the `Configuration`. The operation `provideProjectDetails` is the one of [OC-001]; the only change is the base of its default `directory`, stated in P4. ## Contract: startFromWorkingFolder @@ -21,7 +22,7 @@ Concepts below use the IT terms of [DICT-001] for the PO concepts of [DM-003]. ` | --- | --- | | Operation | `startFromWorkingFolder(configPath: Path [0..1], envPath: Path [0..1]): PromptSet` | | Traces to | `startFromWorkingFolder` in [SSD-002] | -| Concepts | Run, CommandLink, Checkout, WorkingFolder, Configuration | +| Concepts | Run, CommandLink, Checkout, WorkingFolder, ConfigFiles, Configuration | **Preconditions** @@ -34,16 +35,18 @@ Concepts below use the IT terms of [DICT-001] for the PO concepts of [DM-003]. ` - P2. A `Checkout` instance was created and associated with the `Run`, with `path` set to the folder that holds the script's own files, reached through the `CommandLink`, however many links lie between them. - P3. A `WorkingFolder` instance was created and associated with the `Run`, with `path` set to the folder in which the Maintainer started the script. It was not changed by following the `CommandLink`. - P4. The default of `directory` in the `PromptSet` is `./` under the `WorkingFolder`, never under the `Checkout`. -- P5. A `Configuration` instance was created and associated with the `Run` from `configPath`, or from `config.env` in the `Checkout` when `configPath` is absent, and from `envPath`, or from `.env` in the `Checkout` when `envPath` is absent; the validation of [OC-001] `startProjectCreation` P2 and P3 applies. -- P6. The `Run` was associated with a `PromptSet` that is returned. +- P5. A `ConfigFiles` instance was created and associated with the `Run`. Its `configFile` is `configPath` when given, otherwise `config.env` in the `WorkingFolder` when it exists, otherwise `config.env` in the `Checkout`; its `envFile` is chosen in the same way from `envPath` and `.env`. Each file is chosen on its own. The paths are named in the output before any request to a host. +- P6. A `Configuration` instance was created and associated with the `Run` from the `ConfigFiles`; the validation of [OC-001] `startProjectCreation` P2 and P3 applies. +- P7. The `Run` was associated with a `PromptSet` that is returned. **Exceptions** | Condition (failing precondition) | Outcome | | --- | --- | | The `Checkout`'s own files are not found from the link target | The `Run` ends with an error naming the folder it looked in; nothing was changed | -| `config.env` or `.env` is not found in the `Checkout` and no path was given (P5) | The `Run` ends with an error naming the path it looked in and the options `--config` and `--env`; nothing was changed | -| A value in `config.env` or `.env` is malformed (P5) | As in [OC-001] `startProjectCreation`: the error names the key, never its value; nothing was changed | +| `config.env` or `.env` is not named and is in neither the `WorkingFolder` nor the `Checkout` (P5) | The `Run` ends with an error naming both places it looked in and the options `--config` and `--env`; nothing was changed | +| A chosen file is in the `WorkingFolder` and the Maintainer does not confirm it (P5) | The `Run` ends before any request to a host; nothing was changed | +| A value in `config.env` or `.env` is malformed (P6) | As in [OC-001] `startProjectCreation`: the error names the key, never its value; nothing was changed | --- diff --git a/docs/uc-002/sd.md b/docs/uc-002/sd.md index d481059..89501b0 100644 --- a/docs/uc-002/sd.md +++ b/docs/uc-002/sd.md @@ -10,6 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Initial version | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Default configuration files: --config and --env, else ./config.env and ./.env in the working folder, else the checkout's | pending | --- @@ -28,6 +29,7 @@ participant ":Launcher" as L participant ":ProjectCreator" as PC participant ":Checkout" as CK participant ":WorkingFolder" as WF +participant ":ConfigFiles" as CF Maintainer -> L : startFromWorkingFolder(configPath, envPath) activate L @@ -37,13 +39,20 @@ L -> CK : Checkout(path) L -> L : currentFolder() create WF L -> WF : WorkingFolder(path) -alt the Checkout's own files are not found +L -> L : locateConfigFiles(configPath, envPath, checkout, workingFolder) +create CF +L -> CF : ConfigFiles(configFile, envFile) +alt a chosen file is in the working folder + L -> Maintainer : confirm the files and the Gitea address + Maintainer --> L : yes or no +end +alt the Checkout's own files, or both places for a config file, are not found L --> Maintainer : error naming the folder looked in end -L -> PC : startProjectCreation(checkout, workingFolder, configPath, envPath) +L -> PC : startProjectCreation(workingFolder, configFiles) activate PC -alt config.env or .env not found, or a value malformed - PC --> L : error naming the path or the key +alt a value in config.env or .env is malformed + PC --> L : error naming the key end PC --> L : promptSet deactivate PC @@ -56,9 +65,9 @@ deactivate L | Pattern (GRASP / GoF) | Applied to | Rationale | | --- | --- | --- | -| Information Expert | `Launcher.resolveCheckout` | The launcher knows how the script was invoked, so it is the one that can follow the command link | +| Information Expert | `Launcher.resolveCheckout`, `Launcher.locateConfigFiles` | The launcher knows how the script was invoked, so it is the one that can follow the command link | | Controller | `Launcher` | One object takes the system operation and hands the work to `ProjectCreator`; `ProjectCreator` stays unaware of links | -| Low Coupling | `ProjectCreator` receives `checkout` and `workingFolder` as values | The use case [UC-001] runs unchanged whatever way the script was started | +| Low Coupling | `ProjectCreator` receives `workingFolder` and `configFiles` as values | The use case [UC-001] runs unchanged whatever way the script was started | ### Postcondition Coverage @@ -67,14 +76,15 @@ deactivate L | P1 Run | `startFromWorkingFolder` (the run starts with it) | | P2 Checkout | `resolveCheckout(invocation)` and the creation of `Checkout` | | P3 WorkingFolder | `currentFolder()` and the creation of `WorkingFolder` | -| P4 default directory under the WorkingFolder | `startProjectCreation(checkout, workingFolder, ...)`; the prompt default is built from `workingFolder` | -| P5 Configuration | `startProjectCreation` loads `config.env` and `.env` from `checkout` or from the given paths (`load` of [SD-001]) | -| P6 PromptSet | the returned `promptSet` | -| Exceptions: files not found; configuration not found or malformed | the two `alt` fragments | +| P4 default directory under the WorkingFolder | `startProjectCreation(workingFolder, configFiles)`; the prompt default is built from `workingFolder` | +| P5 ConfigFiles | `locateConfigFiles(...)` and the creation of `ConfigFiles`; the paths are named before any request | +| P6 Configuration | `startProjectCreation(workingFolder, configFiles)` loads the two files (`load` of [SD-001]) | +| P7 PromptSet | the returned `promptSet` | +| Exceptions: files not found, not confirmed, or malformed | the `alt` fragments | ### Responsibility Check -`Launcher` only finds the checkout and the working folder; it reads no configuration and makes no repository. `ProjectCreator` keeps every other responsibility of [SD-001]. +`Launcher` only finds the checkout, the working folder and the two files; it reads no configuration and makes no repository. `ProjectCreator` keeps every other responsibility of [SD-001]. --- diff --git a/docs/uc-002/ssd.md b/docs/uc-002/ssd.md index 8808a43..defc644 100644 --- a/docs/uc-002/ssd.md +++ b/docs/uc-002/ssd.md @@ -10,6 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Initial version | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Names the confirmation of a configuration file from the working folder as out of scope | pending | --- @@ -37,7 +38,7 @@ S --> A : creation summary with the project's full path | 3 to 4 | startFromWorkingFolder | configPath (optional), envPath (optional) | prompts for project details whose default directory is under the working folder | 3, 4, 5 | | 5 | provideProjectDetails | the parameters of `provideProjectDetails` in [UC-001] | creation summary that names the full path of the new project | 5, 6 | -Failure flows (extensions 1a, 3a, 4a and 4b of [UC-002]) are out of scope for this diagram: they end the run with a message and add no system operation. `provideProjectDetails` is the operation of [UC-001] and is not repeated in [OC-002]; the only difference is the base of the default `directory`. Making the command link (step 1) and opening the shell (step 2) are done by the Maintainer outside the system, so they are not system operations. +Failure flows (extensions 1a, 3a, 4a and 4b of [UC-002]) are out of scope for this diagram: they end the run with a message and add no system operation. The confirmation of a file from the working folder (extension 4c) is a prompt from the system, out of scope as the consent questions of [SSD-001] are. `provideProjectDetails` is the operation of [UC-001] and is not repeated in [OC-002]; the only difference is the base of the default `directory`. Making the command link (step 1) and opening the shell (step 2) are done by the Maintainer outside the system, so they are not system operations. ## Lifecycle Notes @@ -48,4 +49,5 @@ One script run, as in [UC-001]. The command link persists between runs; the syst [UC-002]: ./uc.md [DM-003]: ./dm.md [OC-002]: ./oc.md +[SSD-001]: ../uc-001/ssd.md [1cd27f7]: https://git.tirsystem.com/TirSystem-BashScript/repo_foundry/commit/1cd27f77ed844773a969210a11de0d8bb98ac98f diff --git a/docs/uc-002/uc.md b/docs/uc-002/uc.md index 9a41f26..a843d7e 100644 --- a/docs/uc-002/uc.md +++ b/docs/uc-002/uc.md @@ -10,6 +10,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Initial version | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Default configuration files: --config and --env, else ./config.env and ./.env in the working folder, else the checkout's; the files used are named and a file from the working folder is confirmed (step 4, extensions 4b and 4c, rules) | pending | --- @@ -25,7 +26,7 @@ - S02 — starting through a link never reads or writes outside the checkout and the current folder - S03 — the README says exactly how to make the command global - **Preconditions:** - - The checkout of RepoFoundry exists and holds `config.env` and `.env` as described in the README, or the Maintainer points to them with `--config` and `--env`. + - The checkout of RepoFoundry exists. `config.env` and `.env` exist as described in the README in the working folder or in the checkout, or the Maintainer points to them with `--config` and `--env`. - A folder that is on the shell's `PATH` exists and the Maintainer may write to it. - **Postconditions (success guarantee):** - A command link exists in a `PATH` folder and leads to the script in the checkout. @@ -37,7 +38,7 @@ 1. The Maintainer makes the script reachable by name: creates a command link in a `PATH` folder that leads to `src/create-project.sh` in the checkout (the README gives the command). 2. The Maintainer opens a shell in the folder in which the new project is to be created (the working folder). 3. The Maintainer starts the script by the name of the command link. -4. The system follows the command link to the checkout, loads its own files from there, and reads `config.env` and `.env` from the checkout, or from the files named by `--config` and `--env`. +4. The system follows the command link to the checkout, loads its own files from there, and chooses `config.env` and `.env`, each one separately: the file named by `--config` or `--env`, otherwise the one in the working folder, otherwise the one in the checkout. It names the files it will use before any request to a host. 5. The system runs [UC-001] (`<>`) with the working folder as the base of the default directory of the new project. 6. The system reports a summary that names the full path of the new project. @@ -49,8 +50,10 @@ 1. The shell reports that the command cannot run; the README says how to recreate the link. - 4a. The checkout's own files cannot be found from the link target: 1. The system stops before any change and names the folder it looked in. -- 4b. `config.env` or `.env` is not found: - 1. The system stops before any change, names the path it looked in and says that `--config` and `--env` can point elsewhere. +- 4b. `config.env` or `.env` is not named, and is in neither the working folder nor the checkout: + 1. The system stops before any change, names both places it looked in and says that `--config` and `--env` can point elsewhere. +- 4c. A chosen file comes from the working folder: + 1. The system names the file and the Gitea address it holds and asks the Maintainer to confirm, default no, before any request to a host; on no, the system stops before any request and any change. ### Special Requirements / Business Rules @@ -58,7 +61,8 @@ | --- | --- | | 1 | The command link is made by the Maintainer with the shell, not by the script; the script never edits `PATH`, a shell profile or a system folder | | 4 | The system finds its own files by following the command link, however many links lie on the way, on every supported platform | -| 4 | `config.env` and `.env` are read from the checkout, never from the working folder, unless `--config` and `--env` name them | +| 4 | `config.env` and `.env` are chosen one by one in this order: `--config` / `--env`; `./config.env` / `./.env` in the working folder; the checkout's. A project may therefore use its own `.env` with the checkout's `config.env` | +| 4 | A folder can hold a `config.env` that points the Gitea address elsewhere, and so send the token there. A file from the working folder is therefore confirmed before the first request, and every file used is named in the output | | 5 | The base of the default directory is the working folder, never the checkout | | 3 to 6 | Behaviour, prompts and summary are the same as when the script is started by its path from the checkout | diff --git a/docs/user-stories.md b/docs/user-stories.md index f98e287..9f08fa6 100644 --- a/docs/user-stories.md +++ b/docs/user-stories.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | US-001.06: AGPL-3.0 default only for a public project with GitHub; US-001.07: the framework's own submodules (qc) are fetched | [1cd27f7] | | 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Added US-002 (global command from the target folder) for UC-002 | [1cd27f7] | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | US-002: the default configuration files are the working folder's, then the checkout's; confirmed and named | pending | --- @@ -136,10 +136,11 @@ One further epic, "Start the script as a global command" ([UC-002]), with one st **Acceptance Criteria** -- Given a command link in a folder on `PATH` that leads to the script, when the Maintainer starts it by name from another folder, then the script runs, finds its own files and reads `config.env` and `.env` from the checkout. +- Given a command link in a folder on `PATH` that leads to the script, when the Maintainer starts it by name from another folder, then the script runs and finds its own files. - Given the Maintainer stands in a folder, when the project directory is not preset, then its default is `./` under that folder, never under the checkout. -- Given `--config` and `--env` name other files, then those are read instead of the checkout's. -- Given a missing file or a broken link, then the script stops before any change and names the folder or path it looked in. +- Given `--config` and `--env` name files, then those are read. Given they are not named, then `./config.env` and `./.env` in the folder the Maintainer stands in are read, each one that exists, and the checkout's file stands in for one that does not. +- Given a file comes from the folder the Maintainer stands in, then the script names it and the Gitea address it holds and asks for a yes, default no, before any request; every file used is named in the output. +- Given a file is named nowhere, in neither folder, or a link is broken, then the script stops before any change and names both places it looked in. - Given the README, then it shows the command that makes the link, the check that it works and a run from a folder that is not the checkout. | Traces to | Size | INVEST exceptions |