feat(tool): dotskit init describes a solution made without dotskit, checked by generating it again

docs/getting-started/dotskit.md

@@ -29,6 +29,9 @@ dotskit new -S Billing --Storage true
 
 # in the solution: a flag for a service it has
 dotskit new -S Orders --MongoDB true
+
+# in a solution made without dotskit: describe it in its manifest
+dotskit init
 ```
 
 `dotskit new` reads from the folder whether to make a solution or to add to one: it looks for
@@ -80,6 +83,43 @@ services has it. The solution's names, `--Database`, `--Deploy`, `--TestFramewor
 `--GitHubCiCd` are set by the first command. A later command takes them from the manifest; a command that
 gives one of them another value is refused.
 
+## A solution made without dotskit
+
+`dotskit new` works from the manifest. A solution made with the template alone, or before 2.8, has none, and
+`dotskit init` writes it: it reads the solution, checks the reading and writes `.dotskit/manifest.json`, and
+nothing else, after a yes.
+
+What it reads:
+
+- the version of the template from `DotNetSolutionKitVersion` in `Directory.Build.props`, there since 2.7.0;
+- the names from `src/services/*.All.sln`; where a dot can belong to either name (`Acme.Corp.Shop`), from the
+  image names of `deploy/build-images.sh`, or from `-N` and `-P` given to the command;
+- the database, the deployment, the test framework and the agent by the files only one choice generates;
+- the flags of `Common` and the root by the files each flag adds;
+- each service under `src/services` with its own API project: its flags by the sections of its
+  `appsettings.json` and the lines only a flag writes, its port by `launchSettings.json`.
+
+The check: `init` generates the solution again by what it read, with that version of the template, and
+compares it with the folder - "412 of 420 files of the template reproduced; these differ: ...". A file that
+differs is a change of the team or a wrong reading; the report lists it so a person can tell which before
+anything relies on the manifest. Files the team added are not counted, and `All.sln` is compared by its
+projects. The check installs the template of that version from nuget.org.
+
+| The folder | What `init` does |
+|---|---|
+| empty | writes nothing, and names `dotskit new -N <Company> -P <Product> -S <Service>` |
+| no `src/services/*.All.sln` | writes nothing: not a solution of DotNetSolutionKit |
+| a solution of 2.7 or later, no manifest | reads it, checks it, shows the manifest and the report, writes it after a yes |
+| a solution of 2.0-2.6, which does not say its version | writes nothing, and asks for `--template-version 2.x.y`; the check then shows how well that version reproduces the solution |
+| generated from the template's sources (version `source`) | writes nothing, and asks for the release it came from with `--template-version` |
+| newer than the tool | writes nothing, and names `dotnet tool update -g SawKing.DotsKit.Tool` |
+| of an earlier major version than the tool | writes nothing: the tool describes solutions of its own major version |
+| a service of another version than the solution | writes nothing, names the service and its version, and asks for the version to describe the solution by with `--template-version`; with it, the check shows what differs |
+| with a manifest that lists every service | writes nothing: "the manifest is current: 2.8.0, services Orders, Billing" |
+| with a manifest, and a service under `src/services` it does not list | adds the service, read from its files, after the same check |
+| services, but no `Common` | writes the manifest without the check and says so: the database and the flags read from `Common` are the template's defaults; `dotskit new` takes `Common` for removed by the team and does not add it back |
+| uncommitted changes in git | runs: it writes only `.dotskit/` |
+
 ## Options
 
 | Option | What it does |
@@ -88,6 +128,7 @@ gives one of them another value is refused.
 | `--force` | resolves a conflict with the template's lines; the team's lines stay in git history |
 | `--no-build` | does not build the solution after writing |
 | `--allow-dirty` | runs on a working tree with uncommitted changes |
+| `--template-version 2.x.y` | `init`: the version the solution was made by, where it does not say it |
 
 ## Exit codes
 
@@ -99,8 +140,6 @@ gives one of them another value is refused.
 
 ## Limits of this version
 
-- `dotskit new` works only in a solution made by `dotskit`. A solution made with the template alone gets
-  its manifest from `dotskit init`, which comes in a later version.
-- The solution and the tool must be of the same version. Upgrading a solution to a new version of the
-  template is `dotskit upgrade`, which comes in a later version; until then use the `dotskit` of the
-  solution's version: `dotnet tool update -g SawKing.DotsKit.Tool --version <version>`.
+- `dotskit new` works in a solution with a manifest: made by `dotskit`, or described by `dotskit init`.
+- `dotskit new` needs a manifest of the tool's version: a solution of an earlier version is brought to it by
+  `dotskit upgrade` first.

docs/getting-started/dotskit.ru.md

@@ -29,6 +29,9 @@ dotskit new -S Billing --Storage true
 
 # в решении: флаг для существующего сервиса
 dotskit new -S Orders --MongoDB true
+
+# в решении, созданном без dotskit: описать его в манифесте
+dotskit init
 ```
 
 `dotskit new` по папке решает, создать решение или добавить в него: ищет `src/services/*.All.sln` в папке
@@ -79,6 +82,43 @@ dotskit new -S Orders --MongoDB true
 задаёт первая команда. Следующие команды берут их из манифеста; команда с другим значением одного из них
 отклоняется.
 
+## Решение, созданное без dotskit
+
+`dotskit new` работает по манифесту. У решения, созданного одним шаблоном или до 2.8, манифеста нет, и его
+пишет `dotskit init`: читает решение, проверяет прочитанное и после «да» записывает `.dotskit/manifest.json`,
+больше ничего.
+
+Что он читает:
+
+- версию шаблона из `DotNetSolutionKitVersion` в `Directory.Build.props`, она там с 2.7.0;
+- имена из `src/services/*.All.sln`; где точка может относиться к любому из имён (`Acme.Corp.Shop`), - из
+  имён образов в `deploy/build-images.sh` или из `-N` и `-P`, переданных команде;
+- базу, развёртывание, тестовый фреймворк и агента по файлам, которые даёт только один вариант;
+- флаги `Common` и корня по файлам, которые добавляет каждый флаг;
+- каждый сервис в `src/services` с собственным API-проектом: его флаги по разделам `appsettings.json` и
+  строкам, которые пишет только флаг, его порт по `launchSettings.json`.
+
+Проверка: `init` генерирует решение заново по прочитанному, той же версией шаблона, и сравнивает с папкой -
+«412 of 420 files of the template reproduced; these differ: ...». Отличающийся файл - это правка команды или
+ошибка чтения; отчёт перечисляет такие файлы, чтобы человек разобрался до того, как на манифест что-то
+опирается. Файлы, добавленные командой, не считаются, `All.sln` сравнивается по проектам. Шаблон этой версии
+проверка ставит с nuget.org.
+
+| Папка | Что делает `init` |
+|---|---|
+| пустая | ничего не пишет и называет `dotskit new -N <Company> -P <Product> -S <Service>` |
+| нет `src/services/*.All.sln` | ничего не пишет: это не решение DotNetSolutionKit |
+| решение 2.7 или новее, без манифеста | читает, проверяет, показывает манифест и отчёт, пишет после «да» |
+| решение 2.0-2.6, которое не называет свою версию | ничего не пишет и просит `--template-version 2.x.y`; проверка затем показывает, насколько эта версия воспроизводит решение |
+| сгенерировано из исходников шаблона (версия `source`) | ничего не пишет и просит выпуск, из которого оно взято, через `--template-version` |
+| новее инструмента | ничего не пишет и называет `dotnet tool update -g SawKing.DotsKit.Tool` |
+| более ранней мажорной версии, чем инструмент | ничего не пишет: инструмент описывает решения своей мажорной версии |
+| сервис другой версии, чем решение | ничего не пишет, называет сервис и его версию и просит версию, которой описать решение, через `--template-version`; с ней проверка покажет, что отличается |
+| с манифестом, в котором есть все сервисы | ничего не пишет: «the manifest is current: 2.8.0, services Orders, Billing» |
+| с манифестом и сервисом в `src/services`, которого в нём нет | добавляет сервис, прочитанный по его файлам, после той же проверки |
+| сервисы есть, а `Common` нет | пишет манифест без проверки и сообщает об этом: база и флаги, которые читаются из `Common`, берутся по умолчанию шаблона; `dotskit new` считает `Common` удалённым командой и не возвращает его |
+| незакоммиченные изменения в git | работает: пишет только `.dotskit/` |
+
 ## Опции
 
 | Опция | Что делает |
@@ -87,6 +127,7 @@ dotskit new -S Orders --MongoDB true
 | `--force` | решает конфликт строками шаблона; строки команды остаются в истории git |
 | `--no-build` | не собирает решение после записи |
 | `--allow-dirty` | работает при незакоммиченных изменениях |
+| `--template-version 2.x.y` | `init`: версия, которой создано решение, если оно её не называет |
 
 ## Коды выхода
 
@@ -98,8 +139,6 @@ dotskit new -S Orders --MongoDB true
 
 ## Ограничения этой версии
 
-- `dotskit new` работает только в решении, созданном `dotskit`. Решению, созданному одним шаблоном,
-  манифест даст `dotskit init`, он появится в следующей версии.
-- Решение и инструмент должны быть одной версии. Обновление решения до новой версии шаблона - это
-  `dotskit upgrade`, он появится в следующей версии; до тех пор используйте `dotskit` версии решения:
-  `dotnet tool update -g SawKing.DotsKit.Tool --version <версия>`.
+- `dotskit new` работает в решении с манифестом: созданном `dotskit` или описанном `dotskit init`.
+- `dotskit new` нужен манифест версии инструмента: решение более ранней версии сначала приводит к ней
+  `dotskit upgrade`.

docs/roadmap.md

@@ -38,7 +38,7 @@ gantt
     a service generated into a solution adds itself to All.sln, on any OS; no script to run :done, s26, after s25, 500ms
     dotskit new - a service or a flag added to a solution, the team's changes kept by a three-way merge :done, s27, after s26, 2000ms
     email and MongoDB in projects of their own - a service carries only its flags' packages (#98) :done, s28, after s25, 800ms
-    dotskit init - a manifest for a solution made without the tool, checked against it (#99) :s29, after s27, 1500ms
+    dotskit init - a manifest for a solution made without the tool, checked against it (#99) :done, s29, after s27, 1500ms
     dotskit upgrade - to the tool's version, one major at a time, the team's changes kept (#100) :s30, after s29, 3000ms
 
     section Next

docs/roadmap.ru.md

@@ -38,7 +38,7 @@ gantt
     a service generated into a solution adds itself to All.sln, on any OS; no script to run :done, s26, after s25, 500ms
     dotskit new - a service or a flag added to a solution, the team's changes kept by a three-way merge :done, s27, after s26, 2000ms
     email and MongoDB in projects of their own - a service carries only its flags' packages (#98) :done, s28, after s25, 800ms
-    dotskit init - a manifest for a solution made without the tool, checked against it (#99) :s29, after s27, 1500ms
+    dotskit init - a manifest for a solution made without the tool, checked against it (#99) :done, s29, after s27, 1500ms
     dotskit upgrade - to the tool's version, one major at a time, the team's changes kept (#100) :s30, after s29, 3000ms
 
     section Next