@ama-openapi/create 0.0.0-placeholder.9 → 13.5.0-prerelease.12

package/LICENSE

@@ -0,0 +1,26 @@
+Copyright Amadeus SAS
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,74 @@
+# Ama OpenAPI Create
+
+[![Stable Version](https://img.shields.io/npm/v/@ama-openapi/create?style=for-the-badge)](https://www.npmjs.com/package/@ama-openapi/create)
+[![Bundle Size](https://img.shields.io/bundlephobia/min/@ama-openapi/create?color=green&style=for-the-badge)](https://www.npmjs.com/package/@ama-openapi/create)
+
+**@ama-openapi/create** is a template generator package that provides scaffolding and templates for creating OpenAPI-based projects.
+It helps developers quickly set up new OpenAPI projects with best practices and a standardized structure.
+
+## Usage
+
+```shell
+npm create @ama-openapi <command> -- [options]
+```
+
+The following global options can be used with any command:
+
+| Options | Description |
+| --- | --- |
+| `--version`, `-v` | Display the current version of the generator. |
+| `--help`, `-h` | Display usage for the CLI commands. |
+
+## Available commands
+
+### Design Project
+
+Create a new [OpenAPI](https://www.openapis.org/) design project via the following command :
+
+```shell
+npm create @ama-openapi design <project-name> -- [options]
+```
+
+The following options are available:
+
+| Options | Default Value | Description |
+| --- | --- | --- |
+| `--target`, `-t` | `.` | Target directory where files will be generated. |
+
+The command will generate a directory with the following structure:
+
+```text
+my-openapi-project/
+├── .vscode/
+│   ├── extensions.json
+│   └── settings.json
+├── apis/
+│   └── example.v1.yaml
+├── models/
+│   └── exampleModel.v1.yaml
+├── responses/
+│   └── exampleResponse.v1.yaml
+├── .gitignore
+├── openapi.manifest.yaml
+├── package.json
+├── redocly.yaml
+├── README.md
+└── renovate.json
+```
+
+> [!NOTE]
+> The package includes several template files that are customized during project generation:
+>
+> - **API specifications**: Example OpenAPI YAML files
+> - **Configuration files**: Project-specific configurations
+> - **Development environment**: VS Code settings and extensions
+> - **Package management**: Pre-configured `package.json` file with common scripts
+> - **Renovate Configuration**: Extends the [@ama-openapi/core preset] package (https://github.com/AmadeusITGroup/otter/tree/main/packages/@ama-openapi/core/renovate/default.json)
+
+## Integration
+
+This generator sets up the repository to work with:
+
+- [@ama-openapi/core](https://www.npmjs.com/package/@ama-openapi/core): Core dependency management functionality
+- [@ama-openapi/redocly-plugin](https://www.npmjs.com/package/@ama-openapi/redocly-plugin): Redocly CLI integration
+- [@ama-openapi/cli](https://www.npmjs.com/package/@ama-openapi/cli): Command to manually retrieve the dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ama-openapi/create",
-  "version": "0.0.0-placeholder.9",
+  "version": "13.5.0-prerelease.12",
   "publishConfig": {
     "access": "public"
   },
@@ -18,7 +18,7 @@
     "postbuild": "cpy 'package.json' 'dist' && patch-package-json-main"
   },
   "peerDependencies": {
-    "@o3r/telemetry": "0.0.0-placeholder.9",
+    "@o3r/telemetry": "~13.5.0-prerelease.12",
     "type-fest": "^4.30.1"
   },
   "peerDependenciesMeta": {
@@ -30,42 +30,41 @@
     }
   },
   "dependencies": {
-    "@ama-openapi/core": "0.0.0-placeholder.9",
+    "@ama-openapi/core": "~13.5.0-prerelease.12",
     "ejs": "~3.1.9",
     "globby": "^11.1.0",
     "tslib": "^2.6.2",
     "yargs": "~18.0.0"
   },
   "devDependencies": {
-    "@angular-devkit/schematics": "~20.3.0",
+    "@angular-devkit/schematics": "~20.3.11",
     "@eslint-community/eslint-plugin-eslint-comments": "^4.4.0",
     "@nx/eslint": "~21.6.0",
     "@nx/eslint-plugin": "~21.6.0",
     "@nx/jest": "~21.6.0",
     "@nx/js": "~21.6.0",
-    "@o3r/build-helpers": "0.0.0-placeholder.9",
-    "@o3r/eslint-config": "0.0.0-placeholder.9",
-    "@o3r/eslint-plugin": "0.0.0-placeholder.9",
-    "@o3r/telemetry": "0.0.0-placeholder.9",
-    "@o3r/test-helpers": "0.0.0-placeholder.9",
-    "@schematics/angular": "~20.3.0",
-    "@stylistic/eslint-plugin": "~5.5.0",
+    "@o3r/build-helpers": "~13.5.0-prerelease.12",
+    "@o3r/eslint-config": "~13.5.0-prerelease.12",
+    "@o3r/eslint-plugin": "~13.5.0-prerelease.12",
+    "@o3r/telemetry": "~13.5.0-prerelease.12",
+    "@o3r/test-helpers": "~13.5.0-prerelease.12",
+    "@schematics/angular": "~20.3.11",
+    "@stylistic/eslint-plugin": "~5.6.0",
     "@types/ejs": "^3.1.2",
     "@types/jest": "~29.5.2",
     "@types/minimist": "^1.2.2",
     "@types/node": "~22.18.0",
-    "@types/pid-from-port": "^1.1.0",
     "@types/semver": "^7.3.13",
     "@types/yargs": "~17.0.33",
-    "@typescript-eslint/parser": "~8.46.0",
-    "angular-eslint": "~20.5.0",
+    "@typescript-eslint/parser": "~8.47.0",
+    "angular-eslint": "~20.6.0",
     "cpy-cli": "^6.0.0",
-    "eslint": "~9.38.0",
+    "eslint": "~9.39.0",
     "eslint-import-resolver-node": "~0.3.9",
     "eslint-import-resolver-typescript": "~4.4.0",
     "eslint-plugin-import": "~2.32.0",
     "eslint-plugin-import-newlines": "~1.4.0",
-    "eslint-plugin-jest": "~29.0.0",
+    "eslint-plugin-jest": "~29.1.0",
     "eslint-plugin-jsdoc": "~54.7.0",
     "eslint-plugin-prefer-arrow": "~1.2.3",
     "eslint-plugin-unicorn": "~60.0.0",
@@ -76,14 +75,13 @@
     "jest-util": "~29.7.0",
     "jsonc-eslint-parser": "~2.4.0",
     "nx": "~21.6.0",
-    "pid-from-port": "^1.1.3",
     "rimraf": "^6.0.1",
     "rxjs": "^7.8.1",
     "semver": "^7.5.2",
     "ts-jest": "~29.4.0",
     "type-fest": "^4.30.1",
     "typescript": "~5.9.2",
-    "typescript-eslint": "~8.46.0"
+    "typescript-eslint": "~8.47.0"
   },
   "generatorDependencies": {
     "@redocly/openapi-core": "~2.11.0"
@@ -92,5 +90,74 @@
     "node": "^20.19.0 || ^22.17.0 || ^24.0.0",
     "yarn": ">=2.0.0 <5.0.0",
     "npm": ">=4"
-  }
-}
+  },
+  "contributors": [
+    {
+      "name": "Yannick Adam",
+      "url": "https://github.com/yannickadam",
+      "email": "yannickadam@users.noreply.github.com"
+    },
+    {
+      "name": "Kilian Panot",
+      "url": "https://github.com/kpanot",
+      "email": "kpanot@users.noreply.github.com"
+    },
+    {
+      "name": "Jeremy Bourgeois",
+      "url": "https://github.com/jbourgeois-1A",
+      "email": "jbourgeois-1A@users.noreply.github.com"
+    },
+    {
+      "name": "Pierre Henri Ginoux",
+      "url": "https://github.com/pginoux-1A",
+      "email": "pginoux-1A@users.noreply.github.com"
+    },
+    {
+      "name": "Mircea Vasile Rednic",
+      "url": "https://github.com/mrednic-1A",
+      "email": "mrednic-1A@users.noreply.github.com"
+    },
+    {
+      "name": "Stephane Dalle",
+      "url": "https://github.com/sdalle-1A",
+      "email": "sdalle-1A@users.noreply.github.com"
+    },
+    {
+      "name": "Nicolas Hoffmann",
+      "url": "https://github.com/nhoffmann-1A",
+      "email": "nhoffmann-1A@users.noreply.github.com"
+    },
+    {
+      "name": "Victor Scaiceanu",
+      "url": "https://github.com/vscaiceanu-1a",
+      "email": "vscaiceanu-1A@users.noreply.github.com"
+    },
+    {
+      "name": "Florian Paul",
+      "url": "https://github.com/fpaul-1A",
+      "email": "fpaul-1A@users.noreply.github.com"
+    },
+    {
+      "name": "Corinne Paulve",
+      "url": "https://github.com/cpaulve-1A",
+      "email": "cpaulve-1A@users.noreply.github.com"
+    },
+    {
+      "name": "Matthieu Crouzet",
+      "url": "https://github.com/matthieu-crouzet",
+      "email": "matthieu-crouzet@users.noreply.github.com"
+    },
+    {
+      "name": "Salome Do",
+      "url": "https://github.com/sdo-1A",
+      "email": "sdo-1A@users.noreply.github.com"
+    }
+  ],
+  "bugs": "https://github.com/AmadeusITGroup/otter/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AmadeusITGroup/otter.git"
+  },
+  "license": "BSD-3-Clause",
+  "homepage": "https://amadeusitgroup.github.io/otter/"
+}

package/templates/.gitignore.template

@@ -1,4 +1,12 @@
+<% if (standardGitignoreNode) { %>
 <%- standardGitignoreNode %>
+<% } else { %>
+# Dependency directory
+node_modules/
+<% } %>
 
-# Ignore external models
+# External models directory
 /<%- externalModelPath %>
+
+# Bundle specifications directory
+/bundle

package/templates/.vscode/extensions.json.template

@@ -1,6 +1,5 @@
 {
   "recommendations": [
-    "42Crunch.vscode-openapi",
-    "stoplight.spectral"
+    "Redocly.openapi-vs-code"
   ]
 }

package/templates/.vscode/settings.json.template

@@ -1,9 +1,12 @@
 {
-  "editor.defaultFormatter": "42Crunch.vscode-openapi",
+  "editor.defaultFormatter": "Redocly.openapi-vs-code",
   "files.readonlyFromPermissions": true,
   "files.readonlyInclude": {
     "**/.cache/**": true,
     "**/node_modules/**": true,
     "**/<%- externalModelPath %>/**/*.{json,yaml,yml}": true
+  },
+  "explorer.fileNesting.patterns": {
+    "package.json": "package-lock.json, openapi.manifest.yaml"
   }
 }

package/templates/README.md.template

@@ -0,0 +1,52 @@
+# <%- packageName %>
+
+This package exposes [OpenApi specification](https://swagger.io/specification/) which can be used to use to generate an SDK or be referred in another specification.
+
+## How to work on it
+
+**Requirements:**
+
+- Code editor [Visual Studio Code](https://code.visualstudio.com/) with the recommended extension (proposed on start).
+- [NodeJs](https://nodejs.org/) with a odd [LTS (or latest) version](https://nodejs.org/en/about/previous-releases).
+
+**Setup:**
+
+```shell
+npm install
+```
+
+### Add dependency
+
+```shell
+npm install <artifact_name>
+```
+
+and refer to its models via config in the [manifest](https://github.com/AmadeusITGroup/otter/tree/main/docs/openapi/MANIFEST_CONFIGURATION.md):
+
+```yaml
+models:
+  <artifact_name>:
+    - models/first-model.yaml
+    - models/second-model.yaml
+```
+
+> [!NOTE]
+> The complete documentation is available on [Dependency concept documentation](https://github.com/AmadeusITGroup/otter/tree/main/docs/openapi/DEPENDENCY_RESOLUTION_CONCEPT.md).
+
+## Repository structure
+
+The current repository has the following structure:
+
+```text
+<%- projectFolder %>/
+├── .vscode/                  # VsCode options and recommended extension
+├── apis/                     # List of the Apis to bundle in the final specification
+├── models/                   # Models to be referred locally and shared
+├── responses/                # List of responses used in the APIs
+├── .gitignore
+├── openapi.manifest.yaml
+├── package.json
+├── redocly.yaml
+├── README.md
+└── renovate.json
+```

package/templates/openapi.manifest.yaml.template

@@ -1 +1 @@
-# yaml-language-server: $schema=https://raw.githubusercontent.com/AmadeusITGroup/otter/refs/heads/feature/open-api/packages/@ama-openapi/core/schemas/manifest.schema.json
+# yaml-language-server: $schema=https://raw.githubusercontent.com/AmadeusITGroup/otter/refs/heads/main/packages/@ama-openapi/core/schemas/manifest.schema.json

package/templates/package.json.template

@@ -1,9 +1,14 @@
 {
-  "$schema": "https://raw.githubusercontent.com/AmadeusITGroup/otter/refs/heads/feature/open-api/packages/@ama-openapi/core/schemas/manifest.schema.json",
+  "$schema": "https://raw.githubusercontent.com/AmadeusITGroup/otter/refs/heads/main/packages/@ama-openapi/core/schemas/manifest.schema.json",
   "name": "<%- packageName %>",
+  "keywords": [
+    "open-api",
+    "ama-open-api",
+    "specification"
+  ],
   "preferUnplugged": true,
   "version": "0.0.0-placeholder",
-  "description": "My Specification description",
+  "description": "Specification for <%- packageName %>",
   "main": "bundle/specification.yaml",
   "files": [
 <%-
@@ -34,5 +39,8 @@
       "module": "./bundle/specification.yaml",
       "default": "./bundle/specification.yaml"
     }
+  },
+  "engines": {
+    "node": "<%- nodeSupportedRange %>"
   }
 }

package/templates/renovate.json.template

@@ -1,6 +1,6 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": [
-    "github>AmadeusITGroup/otter//packages/@ama-openapi/core/renovate#<%- version %>"
+    "github>AmadeusITGroup/otter//packages/@ama-openapi/core/renovate#v<%- version %>"
   ]
 }

package/src/generate-template.d.ts

@@ -1,18 +0,0 @@
-/**
- * Options for template generation
- */
-export interface CreateOptions {
-    /** Target directory */
-    target: string;
-    /** Path to external models */
-    externalModelPath: string;
-    /** Version of the generator */
-    version: string;
-    /** Name of the package/artifact */
-    packageName: string;
-}
-/**
- * Generate Template files
- * @param options
- */
-export declare const generateTemplate: (options: CreateOptions) => Promise<void[]>;

package/src/generate-template.js

@@ -1,50 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateTemplate = void 0;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const core_1 = require("@ama-openapi/core");
-const ejs_1 = require("ejs");
-const globby_1 = require("globby");
-const TEMPLATE_EXTENSION = '.template';
-/**
- * Generate Template files
- * @param options
- */
-const generateTemplate = async (options) => {
-    const { generatorDependencies } = JSON.parse(await node_fs_1.promises.readFile((0, node_path_1.resolve)(__dirname, '..', 'package.json'), { encoding: 'utf8' }));
-    const templatesDirectory = (0, node_path_1.resolve)(__dirname, '..', 'templates');
-    const regExpExtension = new RegExp(`\\${TEMPLATE_EXTENSION}$`);
-    const exportedFiles = [
-        'bundle',
-        'models',
-        ...core_1.DEFAULT_MANIFEST_FILENAMES
-    ];
-    const generatedCode = (0, globby_1.sync)('**/*', { cwd: templatesDirectory, dot: true })
-        .map(async (templatePath) => {
-        const templatePathAbsolute = (0, node_path_1.resolve)(templatesDirectory, templatePath);
-        const content = await (0, ejs_1.renderFile)(templatePathAbsolute, {
-            ...options,
-            exportedFiles,
-            redoclyVersion: generatorDependencies['@redocly/openapi-core'],
-            standardGitignoreNode: await (await fetch('https://www.toptal.com/developers/gitignore/api/node')).text()
-        }, { async: true });
-        return {
-            templatePath,
-            content
-        };
-    })
-        .map(async (file) => {
-        const { templatePath, content } = await file;
-        const outputPath = (0, node_path_1.resolve)(options.target, templatePath.replace(regExpExtension, ''));
-        try {
-            await node_fs_1.promises.mkdir((0, node_path_1.dirname)(outputPath), { recursive: true });
-        }
-        catch {
-            // ignore error if folder already exists
-        }
-        await node_fs_1.promises.writeFile(outputPath, content, { encoding: 'utf8' });
-    });
-    return Promise.all(generatedCode);
-};
-exports.generateTemplate = generateTemplate;

package/src/index.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/src/index.js

@@ -1,38 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const core_1 = require("@ama-openapi/core");
-const yargs = require("yargs");
-const helpers_1 = require("yargs/helpers");
-const generate_template_1 = require("./generate-template");
-void (async () => {
-    const version = JSON.parse(await node_fs_1.promises.readFile((0, node_path_1.resolve)(__dirname, '..', 'package.json'), { encoding: 'utf8' })).version;
-    await yargs((0, helpers_1.hideBin)(process.argv))
-        .option('target', {
-        alias: 't',
-        type: 'string',
-        description: 'Target directory to generate the files into',
-        default: process.cwd()
-    })
-        .command('design <name>', 'Name of the artifact / package to generate', (y) => {
-        return y.positional('name', {
-            type: 'string',
-            demandOption: true,
-            describe: 'Name of the artifact / package to generate'
-        });
-    }, async (argv) => {
-        const options = {
-            target: argv.target,
-            externalModelPath: core_1.OUTPUT_DIRECTORY,
-            version,
-            packageName: argv.name
-        };
-        await (0, generate_template_1.generateTemplate)(options);
-    })
-        .version(version)
-        .alias('h', 'help')
-        .alias('v', 'version')
-        .parse();
-})();