Add Archify | New Model… with three C4 examples and Open Model in the Explorer menu

- templates/models: C4 - Standard Web App, C4 - E-Shop, C4 - Event-Based
  Integration; each a complete model (main.archify, registry, context,
  containers, components) that validates
- archify.newModel: pick an example and a folder name, copy it, name the
  model after the folder, open the model page
- Explorer menu: New Model… on folders, Open Model on .archify and
  .archify-registry files; File → New File… lists New Model…
- unit test validates every example end to end; integration test runs the
  command; README, CHANGELOG, docs/model.md

src/commands/modelCommands.ts

@@ -1,7 +1,21 @@
 import * as vscode from 'vscode';
+import { MODEL_EXAMPLES, mainFromExample } from '../language/examples';
+import { diagramName, invalidNameReason } from '../language/templates';
 import { MAIN_FILE } from '../model/format';
+import { readText } from '../util/files';
 import { DIAGRAM_EDITOR_VIEW_TYPE } from '../views/diagramView';
-import { CommandContext, targetUri } from './context';
+import { CommandContext, exists, targetUri } from './context';
+
+/** Folder the new model folder goes into: the clicked folder (or a file's folder), else a workspace folder. */
+async function parentFolder(arg?: unknown): Promise<vscode.Uri | undefined> {
+  if (arg instanceof vscode.Uri) {
+    const stat = await vscode.workspace.fs.stat(arg);
+    return stat.type & vscode.FileType.Directory ? arg : vscode.Uri.joinPath(arg, '..');
+  }
+  const folders = vscode.workspace.workspaceFolders ?? [];
+  if (folders.length <= 1) return folders[0]?.uri;
+  return (await vscode.window.showWorkspaceFolderPick({ placeHolder: 'Folder for the new model' }))?.uri;
+}
 
 export function modelCommands(ctx: CommandContext): vscode.Disposable[] {
   return [
@@ -15,5 +29,42 @@ export function modelCommands(ctx: CommandContext): vscode.Disposable[] {
       }
       await vscode.commands.executeCommand('vscode.openWith', vscode.Uri.joinPath(root, MAIN_FILE), DIAGRAM_EDITOR_VIEW_TYPE, vscode.ViewColumn.Active);
     }),
+
+    // Creates a new model folder from one of the shipped examples and opens its model page.
+    vscode.commands.registerCommand('archify.newModel', async (arg?: unknown) => {
+      const picked = await vscode.window.showQuickPick(
+        MODEL_EXAMPLES.map((example) => ({ label: example.label, description: example.description, example })),
+        { title: 'Archify | New Model', placeHolder: 'Example to start from' },
+      );
+      if (!picked) return;
+      const { example } = picked;
+
+      let parent = await parentFolder(arg);
+      if (!parent) {
+        const chosen = await vscode.window.showOpenDialog({ title: 'Archify | New Model', canSelectFiles: false, canSelectFolders: true, openLabel: 'Create model here' });
+        parent = chosen?.[0];
+        if (!parent) return;
+      }
+      const name = await vscode.window.showInputBox({
+        title: 'Archify | New Model',
+        prompt: `Folder name in ${vscode.workspace.asRelativePath(parent, true)}`,
+        value: example.folder,
+        validateInput: async (value) =>
+          invalidNameReason(value) ?? ((await exists(vscode.Uri.joinPath(parent, diagramName(value)))) ? `${diagramName(value)} already exists.` : undefined),
+      });
+      if (name === undefined) return;
+      const folderName = diagramName(name);
+      const target = vscode.Uri.joinPath(parent, folderName);
+      if (await exists(target)) {
+        vscode.window.showWarningMessage(`Archify: ${vscode.workspace.asRelativePath(target, true)} already exists.`);
+        return;
+      }
+
+      const source = vscode.Uri.joinPath(ctx.extension.extensionUri, 'templates', 'models', example.folder);
+      await vscode.workspace.fs.copy(source, target, { overwrite: false });
+      const main = vscode.Uri.joinPath(target, MAIN_FILE);
+      await vscode.workspace.fs.writeFile(main, Buffer.from(mainFromExample(await readText(main), folderName, example), 'utf8'));
+      await vscode.commands.executeCommand('vscode.openWith', main, DIAGRAM_EDITOR_VIEW_TYPE);
+    }),
   ];
 }

src/language/examples.ts

@@ -0,0 +1,34 @@
+import { parseDocument } from 'yaml';
+import { modelIdFromName, titleFromName } from './templates';
+
+/**
+ * Example models shipped with the extension (templates/models/<folder>).
+ * "Archify | New Model…" offers them; each is a complete model folder:
+ * main.archify, registry/*.archify-registry and diagrams by level.
+ */
+export interface ModelExample {
+  /** Folder under templates/models and the default name of the new model folder. */
+  folder: string;
+  label: string;
+  description: string;
+}
+
+export const MODEL_EXAMPLES: readonly ModelExample[] = [
+  { folder: 'c4-standard-web-app', label: 'C4 - Standard Web App', description: 'Single-page app, API, database, cache, file storage, identity provider' },
+  { folder: 'c4-e-shop', label: 'C4 - E-Shop', description: 'Web shop, API, worker, queue, payment and email providers' },
+  { folder: 'c4-event-based-integration', label: 'C4 - Event-Based Integration', description: 'Event bus, router, dead-letter queue, event store, consumers' },
+];
+
+/**
+ * The example's main.archify for a new model folder. When the folder keeps
+ * the example's name the file is used as written; otherwise id, name and the
+ * overview title follow the folder name and the description is kept.
+ */
+export function mainFromExample(mainText: string, folderName: string, example: ModelExample): string {
+  if (folderName === example.folder) return mainText;
+  const doc = parseDocument(mainText);
+  doc.setIn(['model', 'id'], modelIdFromName(folderName));
+  doc.setIn(['model', 'name'], titleFromName(folderName));
+  if (doc.hasIn(['meta', 'title'])) doc.setIn(['meta', 'title'], `${titleFromName(folderName)} — overview`);
+  return doc.toString({ lineWidth: 0, flowCollectionPadding: false });
+}