create-next-pro-cli 0.1.30 → 0.1.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-next-pro-cli",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "Advanced Next.js project scaffolder with i18n, Tailwind, App Router and more.",
   "repository": {
     "type": "git",

package/templates/Projects/default/.agents/skills/create-next-pro-addapi/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: create-next-pro-addapi
+description: Add an App Router API route to a generated create-next-pro project. Use when Codex needs to create a safe route.ts path, then replace the example response and review validation and authentication.
+---
+
+# Add an API route
+
+## Preconditions
+
+- Work from the generated project root containing `cnp.config.json`.
+- Express nested route segments with dots, not filesystem separators.
+- Use only safe non-empty segments.
+
+## Command
+
+```bash
+create-next-pro addapi <route[.child...]> [--json]
+```
+
+## Effects
+
+`addapi users.profile` creates or preserves:
+
+```text
+src/app/api/users/profile/route.ts
+```
+
+The command creates the route directory inside the project boundary and writes the template only when `route.ts` is missing. An existing handler is preserved and reported as `unchanged`.
+
+## Workflow
+
+1. Convert the intended URL hierarchy to a dot-separated logical name.
+2. Run the command with `--json`.
+3. Confirm the reported API route path is correct.
+4. Replace the generated example response with the required behavior.
+5. Add input validation, authorization, authentication, error handling, and tests appropriate to the endpoint.
+6. Run the project checks.
+
+## Examples
+
+Create a health endpoint:
+
+```bash
+create-next-pro addapi health
+```
+
+Create a nested endpoint non-interactively:
+
+```bash
+create-next-pro addapi users.profile --json
+```
+
+## Validate
+
+```bash
+bun run check
+# or: npm run check
+# or: pnpm run check
+```
+
+Do not report the API as implemented merely because the template was generated. Complete the required review next step and preserve an existing route handler.

package/templates/Projects/default/.agents/skills/create-next-pro-addcomponent/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: create-next-pro-addcomponent
+description: Add a global or page-scoped UI component to a generated create-next-pro project. Use when Codex needs to create a component and its locale message keys without overwriting existing component code.
+---
+
+# Add a component
+
+## Preconditions
+
+- Work from the generated project root containing `cnp.config.json`.
+- Use one safe component-name segment.
+- Use a simple or `Parent.Child` page scope when `--page` is present.
+
+## Command
+
+```bash
+create-next-pro addcomponent <Component> [--page <Page|Parent.Child>] [--json]
+```
+
+`-P` is the short form of `--page`. The option requires a page name.
+
+## Effects
+
+Without `--page`, the command creates:
+
+- `src/ui/_global/<Component>.tsx`
+- a `<Component>` key in `messages/<locale>/_global_ui.json`
+
+With `--page Account.Security`, the command creates:
+
+- `src/ui/Account/Security/<Component>.tsx`
+- a `<Component>` key in the `Account.Security` translation namespace
+
+The component name is normalized to a TypeScript identifier. Existing component code and existing message keys are preserved and reported as `unchanged`.
+
+## Workflow
+
+1. Decide whether the component is global or owned by one page.
+2. Verify the page scope and translation namespace when using `--page`.
+3. Run the complete command with `--json`.
+4. Inspect the component and per-locale message events.
+5. Implement the component behavior and review all generated translations.
+6. Run the project checks.
+
+## Examples
+
+Create a global component:
+
+```bash
+create-next-pro addcomponent Alert
+```
+
+Create a component for a nested page:
+
+```bash
+create-next-pro addcomponent PasswordForm --page Account.Security --json
+```
+
+## Validate
+
+```bash
+bun run check
+# or: npm run check
+# or: pnpm run check
+```
+
+Confirm the component path and all translation paths reported by the JSON result. Do not claim that an existing component was regenerated when its event is `unchanged`.

package/templates/Projects/default/.agents/skills/create-next-pro-addlanguage/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: create-next-pro-addlanguage
+description: Add and register a two-letter locale in a generated create-next-pro project. Use when Codex needs to copy the default locale, update routing and the typed message registry, and then translate every copied message before delivery.
+---
+
+# Add a language
+
+## Preconditions
+
+- Work from the generated project root containing `cnp.config.json`.
+- Confirm internationalization is enabled.
+- Use a recognized lowercase two-letter language code.
+- Keep the default locale directory, locale aggregator, routing file, and message registry consistent before running the command.
+
+## Command
+
+```bash
+create-next-pro addlanguage <locale> [--json]
+```
+
+Human mode offers an autocomplete menu when the locale is omitted. JSON mode always requires the locale argument.
+
+## Effects
+
+For `addlanguage de`, the command:
+
+- copies every file from `messages/<default-locale>/` to `messages/de/`;
+- creates `messages/de.ts` with imports redirected to `./de/`;
+- adds `de` to `src/lib/i18n/routing.ts`;
+- imports and exposes `de` in `src/lib/i18n/messages.ts`.
+
+The copied JSON values remain in the source language. They are not translated and are not ready for delivery.
+
+A fully configured locale returns `unchanged`. A partially configured locale fails with `INCONSISTENT_LOCALE` before writing; inspect and repair the inconsistent files instead of retrying blindly.
+
+## Workflow
+
+1. Identify the current default locale and the target two-letter code.
+2. Run the complete command with `--json`.
+3. Inspect every `copied`, `created`, and `updated` event.
+4. Read the required `translate` next step and translate every listed JSON file into the target language.
+5. Keep placeholders, ICU syntax, keys, and nested object shapes unchanged while translating values.
+6. Review routing and the typed message registry.
+7. Run the project checks in every supported locale.
+
+## Examples
+
+Select a locale interactively:
+
+```bash
+create-next-pro addlanguage
+```
+
+Add German non-interactively:
+
+```bash
+create-next-pro addlanguage de --json
+```
+
+## Validate
+
+```bash
+bun run check
+# or: npm run check
+# or: pnpm run check
+```
+
+Do not mark the locale complete until every path in the `translate` next step has been reviewed and translated. Never expose `.env` values while testing authentication in the new locale.

package/templates/Projects/default/.agents/skills/create-next-pro-addlib/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: create-next-pro-addlib
+description: Add a library directory or library.module to a generated create-next-pro project. Use when Codex needs to create a reusable module and maintain its index exports while preserving existing implementation files.
+---
+
+# Add a library
+
+## Preconditions
+
+- Work from the generated project root containing `cnp.config.json`.
+- Use `library` for an empty library shell or `library.module` for a generated module.
+- Use at most two safe dot-separated segments.
+
+## Command
+
+```bash
+create-next-pro addlib <library|library.module> [--json]
+```
+
+## Effects
+
+`addlib analytics` creates or preserves:
+
+- `src/lib/analytics/`
+- `src/lib/analytics/index.ts`
+
+`addlib analytics.trackEvent` additionally creates or preserves:
+
+- `src/lib/analytics/trackEvent.ts`
+- the corresponding import and export in `src/lib/analytics/index.ts`
+
+Existing module implementations are never overwritten. The index is updated only when the required import or export is missing.
+
+## Workflow
+
+1. Choose whether the task needs only a library namespace or a concrete module.
+2. Run the command with `--json`.
+3. Inspect the directory, module, and index events.
+4. Implement and review the generated module placeholder.
+5. Ensure the index exports the module exactly once.
+6. Run the project checks.
+
+## Examples
+
+Create a library shell:
+
+```bash
+create-next-pro addlib analytics
+```
+
+Create and register a module:
+
+```bash
+create-next-pro addlib analytics.trackEvent --json
+```
+
+## Validate
+
+```bash
+bun run check
+# or: npm run check
+# or: pnpm run check
+```
+
+On a repeated command, expect the existing module to remain intact. Review the result events before editing the index manually.

package/templates/Projects/default/.agents/skills/create-next-pro-addpage/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: create-next-pro-addpage
+description: Add a simple or Parent.Child page to a generated create-next-pro project. Use when Codex needs to create App Router files, page UI, and localized messages while preserving existing page resources.
+---
+
+# Add a page
+
+## Preconditions
+
+- Work from the generated project root containing `cnp.config.json`.
+- Use a safe logical page name with one segment or exactly `Parent.Child`.
+- Inspect the requested route and UI scope before generating files.
+
+## Command
+
+```bash
+create-next-pro addpage <Page|Parent.Child> [options] [--json]
+```
+
+With no file options, the command selects `layout`, `page`, and `loading`.
+
+| Long option      | Short option | Generated route file |
+| ---------------- | ------------ | -------------------- |
+| `--layout`       | `-L`         | `layout.tsx`         |
+| `--page`         | `-P`         | `page.tsx`           |
+| `--loading`      | `-l`         | `loading.tsx`        |
+| `--not-found`    | `-n`         | `not-found.tsx`      |
+| `--error`        | `-e`         | `error.tsx`          |
+| `--global-error` | `-g`         | `global-error.tsx`   |
+| `--route`        | `-r`         | `route.ts`           |
+| `--template`     | `-t`         | `template.tsx`       |
+| `--default`      | `-d`         | `default.tsx`        |
+
+Short options can be combined, for example `-PLl`. Unknown options fail with `INVALID_ARGUMENT`.
+
+## Effects
+
+For `Account.Security`, expect resources under:
+
+- `src/app/[locale]/Account/Security/`
+- `src/ui/Account/Security/page-ui.tsx`
+- `messages/<locale>/Account.json` at the `Security` namespace
+- `messages/<locale>.ts` when the message file needs registration
+
+The command creates only missing code files and preserves existing ones as `unchanged`. It prepares all required templates and locale updates before writing.
+
+## Workflow
+
+1. Select the logical page name and only the required route file options.
+2. Run the command with `--json`.
+3. Inspect route, UI, translation, and aggregator events separately.
+4. Review every generated UI and route file.
+5. Replace or translate placeholder messages in every locale.
+6. Run the project checks.
+
+## Examples
+
+Create the default page resources:
+
+```bash
+create-next-pro addpage Profile
+```
+
+Create only `page.tsx`, `layout.tsx`, and the page UI for a nested page:
+
+```bash
+create-next-pro addpage Account.Security -PL --json
+```
+
+Create an error and not-found boundary:
+
+```bash
+create-next-pro addpage Checkout --error --not-found --json
+```
+
+## Validate
+
+```bash
+bun run check
+# or: npm run check
+# or: pnpm run check
+```
+
+Confirm every `created` or `updated` event path exists. A repeated command should preserve existing code and normally report those resources as `unchanged`.

package/templates/Projects/default/.agents/skills/create-next-pro-addtext/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: create-next-pro-addtext
+description: Set a dot-separated translation key across every configured locale in a generated create-next-pro project. Use when Codex needs to create or replace one message value consistently and then localize the propagated text.
+---
+
+# Add or update translation text
+
+## Preconditions
+
+- Work from the generated project root containing `cnp.config.json`.
+- Confirm internationalization is enabled and at least one locale directory exists.
+- Use a path with a message file and at least one key, such as `dashboard.welcome`.
+
+## Command
+
+```bash
+create-next-pro addtext <file.key[.nested...]> [text...] [--json]
+```
+
+If text is omitted, the CLI derives a title-cased value from the final key. Provide the intended source text explicitly for agentic work.
+
+## Effects
+
+The first path segment selects `messages/<locale>/<file>.json`. Remaining segments select the nested key. The command writes the same value to every configured locale:
+
+- a missing file or key is created;
+- a different existing value is updated with `replaced: true` in event detail;
+- an identical value is reported as `unchanged`.
+
+Invalid JSON or a scalar encountered where an object is required causes an error before any prepared writes are applied.
+
+## Workflow
+
+1. Inspect existing message files and select the canonical dot path.
+2. Run the command with explicit text and `--json`.
+3. Inspect every per-locale event and whether a previous value was replaced.
+4. Translate the propagated source value separately in each locale where required.
+5. Preserve message keys, interpolation placeholders, and ICU syntax.
+6. Run the project checks.
+
+## Examples
+
+Set a value in human mode:
+
+```bash
+create-next-pro addtext dashboard.welcome "Welcome back"
+```
+
+Set a nested value non-interactively:
+
+```bash
+create-next-pro addtext account.security.passwordHint "Use at least 12 characters" --json
+```
+
+## Validate
+
+```bash
+bun run check
+# or: npm run check
+# or: pnpm run check
+```
+
+The initial value is intentionally identical across locales. Complete the required translation next step rather than assuming propagation performed translation.

package/templates/Projects/default/.agents/skills/create-next-pro-create-project/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: create-next-pro-create-project
+description: Scaffold a new create-next-pro Next.js project. Use when Codex needs to create a generated project, select a safe destination, handle an existing target, or perform the initial install, environment setup, checks, and local start.
+---
+
+# Create a project
+
+## Preconditions
+
+- Work from the parent directory that should contain the new project.
+- Choose a safe single-segment project name.
+- Complete the CLI onboarding once in human mode if the JSON result reports `ONBOARDING_REQUIRED`.
+- Inspect an existing destination before deciding whether deletion with `--force` is authorized.
+
+## Command
+
+```bash
+create-next-pro <project-name> [--force] [--json]
+```
+
+Use letters, digits, hyphens, or underscores in the project name. Do not pass an absolute path, a separator, `.` or `..`. JSON mode requires the project name. Without a name, human mode opens the interactive project assistant.
+
+Use `--force` only when replacement of the exact child destination is intended. The CLI deletes that destination before copying the template and does not merge its contents.
+
+## Workflow
+
+1. Resolve the intended parent directory and project name.
+2. Run the command with `--json` for agentic execution.
+3. Require `status: "success"` and inspect every event.
+4. Confirm the project contains `package.json`, `tsconfig.json`, `cnp.config.json`, `AGENTS.md`, `.agents/skills`, and `.env.example`.
+5. Confirm `.env`, `.git`, caches, build output, and internal agent context were not copied.
+6. Enter the project and install with one package manager.
+7. Copy `.env.example` to the local `.env`, review the development values, run the full checks, and start the development server.
+
+The scaffold updates the package name and import alias, removes the source template's `packageManager` field, and leaves the generated project free to use Bun, npm, or pnpm.
+
+## Examples
+
+Human output:
+
+```bash
+create-next-pro customer-portal
+```
+
+Agentic output:
+
+```bash
+create-next-pro customer-portal --json
+```
+
+Explicitly replace an inspected destination:
+
+```bash
+create-next-pro customer-portal --force --json
+```
+
+Do not retry `TARGET_EXISTS` with `--force` automatically. Obtain authorization or choose another project name.
+
+## Validate
+
+With Bun only:
+
+```bash
+cd customer-portal
+bun install
+cp .env.example .env
+bun run check
+bun run dev
+```
+
+Equivalent npm or pnpm workflows:
+
+```bash
+npm install && npm run check
+pnpm install && pnpm run check
+```

package/templates/Projects/default/.agents/skills/create-next-pro-rmpage/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: create-next-pro-rmpage
+description: Remove a catalogued page and its associated route, UI, and message resources from a generated create-next-pro project. Use when Codex needs a confirmed, project-confined page deletion in direct or interactive mode.
+---
+
+# Remove a page
+
+## Preconditions
+
+- Work from the generated project root containing `cnp.config.json`.
+- Confirm the target is a page that contains an actual `page.tsx` and appears in the CLI page catalog.
+- Review uncommitted work and references to the route before deletion.
+- Use a simple logical name or `Parent.Child`, never a filesystem path.
+
+## Command
+
+```bash
+create-next-pro rmpage [Page|Parent.Child] [--json]
+```
+
+Without a name, human mode displays an autocomplete tree and asks for confirmation. JSON mode requires the explicit page name and never prompts.
+
+## Effects
+
+The command can remove:
+
+- the page's App Router directory;
+- the matching `src/ui` page directory;
+- a top-level locale JSON file and its aggregator registration; or
+- only the nested message key for `Parent.Child`.
+
+The page catalog excludes technical directories and routes without `page.tsx`. Resolution and deletion remain confined to the project. Shared parents and unrelated files are preserved.
+
+## Workflow
+
+1. Discover the target with human autocomplete or confirm its logical name from the project structure.
+2. Inspect references, navigation entries, tests, and uncommitted changes that may depend on the page.
+3. Prefer an explicit name with `--json` for agentic deletion.
+4. Require a successful result and inspect every `deleted`, `updated`, and `unchanged` event.
+5. Confirm deleted paths are absent and preserved parents still exist.
+6. Remove or update references only after reviewing the CLI result.
+7. Run the project checks.
+
+## Examples
+
+Select and confirm a page interactively:
+
+```bash
+create-next-pro rmpage
+```
+
+Remove a nested page non-interactively:
+
+```bash
+create-next-pro rmpage Account.Security --json
+```
+
+## Validate
+
+```bash
+bun run check
+# or: npm run check
+# or: pnpm run check
+```
+
+Treat `TARGET_NOT_FOUND` as a request or state mismatch. Do not substitute a filesystem deletion command, and do not infer deletion from exit code alone.

package/templates/Projects/default/AGENTS.md

@@ -0,0 +1,83 @@
+# Project Agent Instructions
+
+This repository was generated by `create-next-pro`. Follow these instructions when an agent creates or evolves project resources with the CLI.
+
+## Work from the correct directory
+
+- Run project creation from the parent directory that will contain the new project.
+- Run every `add*` command and `rmpage` from the generated project root, where `cnp.config.json` is located.
+- Prefer the installed `create-next-pro` executable. If it is unavailable, use `bunx create-next-pro-cli`, `npx create-next-pro-cli`, or `pnpm dlx create-next-pro-cli` with the same arguments.
+- Read the linked command skill before invoking a mutation.
+
+## Choose one package manager
+
+Bun is the primary example in this project. A Bun workflow does not require a separate Node.js installation. npm and pnpm remain supported alternatives for generated projects.
+
+Use one command family consistently in a working copy:
+
+```bash
+bun install
+bun run check
+bun run dev
+```
+
+```bash
+npm install
+npm run check
+npm run dev
+```
+
+```bash
+pnpm install
+pnpm run check
+pnpm run dev
+```
+
+Do not commit an additional lockfile unless the project has intentionally changed its package manager policy.
+
+## Use the agentic output contract
+
+- Add `--json` to non-interactive agent commands.
+- Pass every required argument in JSON mode. The CLI never opens prompts in that mode.
+- Parse the single JSON document from standard output. Do not scrape the human renderer.
+- Check `status`, `events`, `nextSteps`, and `error`, not only `exitCode`.
+- Treat `success`, `unchanged`, and `cancelled` as exit code `0`. Treat `failed` as exit code `1`.
+- Verify every `created`, `copied`, or `updated` path and confirm every `deleted` path is absent.
+- Complete all required `nextSteps` before considering the task finished.
+
+## Protect project data
+
+- Never print, commit, or include `.env` values in prompts, logs, events, or reports.
+- Use `.env.example` as the public development contract. Create a local file with `cp .env.example .env`, then replace credentials for production.
+- Use `--force` only after resolving and inspecting the exact destination. It deletes the existing child destination before scaffolding.
+- Pass logical names, not filesystem paths. Names use safe dot-separated segments such as `account.security`; never pass absolute paths, slashes, empty segments, or `..`.
+- Preserve existing source files. The add commands report existing resources as `unchanged` instead of overwriting them.
+- Use `rmpage` only for a page returned by the CLI page catalog, and inspect deletion events before making follow-up edits.
+
+## CLI operations
+
+| Operation        | Purpose                                                         | Skill                                                                                       |
+| ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Create a project | Scaffold the complete Next.js project in a new child directory. | [`$create-next-pro-create-project`](.agents/skills/create-next-pro-create-project/SKILL.md) |
+| `addpage`        | Add a route, page UI, and localized message resources.          | [`$create-next-pro-addpage`](.agents/skills/create-next-pro-addpage/SKILL.md)               |
+| `addcomponent`   | Add a global or page-scoped UI component and messages.          | [`$create-next-pro-addcomponent`](.agents/skills/create-next-pro-addcomponent/SKILL.md)     |
+| `addlib`         | Add a library directory or a library module and export.         | [`$create-next-pro-addlib`](.agents/skills/create-next-pro-addlib/SKILL.md)                 |
+| `addapi`         | Add an App Router API route handler.                            | [`$create-next-pro-addapi`](.agents/skills/create-next-pro-addapi/SKILL.md)                 |
+| `addlanguage`    | Copy and register a new locale that must then be translated.    | [`$create-next-pro-addlanguage`](.agents/skills/create-next-pro-addlanguage/SKILL.md)       |
+| `addtext`        | Set one translation path across all configured locales.         | [`$create-next-pro-addtext`](.agents/skills/create-next-pro-addtext/SKILL.md)               |
+| `rmpage`         | Remove a catalogued page and its associated resources safely.   | [`$create-next-pro-rmpage`](.agents/skills/create-next-pro-rmpage/SKILL.md)                 |
+
+## Global options
+
+- `--json`: emit one deterministic JSON document without prompts or decorative output.
+- `--force`: replace an existing project destination during project creation only.
+- `--reconfigure`: rerun the interactive CLI configuration assistant.
+- `--help`: display public command help.
+- `--version` or `-v`: display the CLI version.
+
+## Finish every mutation
+
+1. Inspect the CLI result and all changed paths.
+2. Complete required review or translation steps.
+3. Run `bun run check`, `npm run check`, or `pnpm run check` with the selected package manager.
+4. Report the command, status, affected paths, and any remaining required work.