rpr-cli 0.1.1__py3-none-any.whl

rpr/scaffolds/instructions/rust-engine.instructions.md

@@ -0,0 +1,40 @@
+---
+applyTo: "packages/python/*-engine/**"
+description: "Rust + PyO3 engine build, lint, and Python bindings"
+---
+
+# Rust Engine
+
+Use Rust for performance-sensitive code that needs a Python-facing API. This package uses PyO3 for bindings and Maturin as the Python build backend.
+
+## Structure
+
+- Package root: `packages/python/{name}-engine`
+- Rust source: `packages/python/{name}-engine/src/lib.rs`
+- Python build metadata: `packages/python/{name}-engine/pyproject.toml`
+- Type stubs: keep a `.pyi` file next to the package root for editor support
+
+## Build and Tooling
+
+- Use `pyo3 = { version = "0.23", features = ["extension-module"] }` for Python bindings.
+- Use Maturin as the build backend in `pyproject.toml`.
+- Keep the PyO3 module name in underscore form so it matches the generated Rust module and stub file names.
+- Use Rayon only when the engine actually performs parallel work. Do not add concurrency primitives speculatively.
+
+## NX Targets
+
+- `engine:build` should run `uv run maturin develop` from the engine package directory.
+- `engine:lint` should run `cargo clippy --all-targets --all-features -- -D warnings`.
+- `engine:format` should run `cargo fmt --check`.
+
+## Binding Conventions
+
+- Keep the Python-facing API small and explicit. Expose a small set of well-typed functions rather than mirroring large internal Rust modules.
+- Use `#[pyfunction]` for individual exported functions and register them in the `#[pymodule]` entrypoint.
+- Favor simple Python-friendly return types unless there is a strong reason to expose a richer binding surface.
+- Update the `.pyi` stub whenever the exported Python API changes.
+
+## Package Boundaries
+
+- Keep domain business rules in the Python domain layer unless the logic is genuinely performance-sensitive or requires Rust-specific capabilities.
+- Treat the engine as an implementation detail behind a stable Python-facing contract.

rpr/scaffolds/instructions/setup-guide.instructions.md

@@ -0,0 +1,86 @@
+---
+applyTo: "pyproject.toml,nx.json,package.json,.pre-commit-config.yaml,.gitignore,.env.example,apps/*/project.json,apps/*/pyproject.toml,packages/**/project.json,packages/**/pyproject.toml,packages/**/alembic.ini,packages/**/migrations/**"
+description: "Use when checking or updating NX + UV monorepo setup, project layout, naming, workspace membership, or generated command surfaces"
+---
+
+# NX + UV Setup Guide
+
+Use this guidance when validating or changing the monorepo setup against the RPR workspace contract.
+
+## Workspace Contract
+
+- Treat NX as the task surface for the workspace.
+- Treat UV as the Python environment and dependency manager.
+- Keep root workspace setup, generated project layout, and documented commands in sync.
+- If the generated code and the guide disagree, update one so they match instead of leaving drift in place.
+
+## Root Bootstrap
+
+- Bootstrap NX as an empty workspace and keep Nx Cloud disabled during initialization and in `nx.json`.
+- Initialize UV at the root and keep the root `pyproject.toml` as the source of truth for workspace members, Python dev dependencies, Ruff, and pytest discovery.
+- Keep the root `package.json` aligned with the actual Nx targets the workspace generates.
+- Keep `.pre-commit-config.yaml` valid YAML and make sure every documented hook command is runnable in the generated workspace.
+
+## Naming And Layout
+
+- Use kebab-case for project roots and Nx project names.
+- Keep the frontend app at `apps/{name}-web`.
+- Keep the FastAPI app at `apps/{name}-api`.
+- Keep the reusable React library at `packages/node/{name}-ui`.
+- Keep the dedicated Storybook host at `packages/node/sb`.
+- Keep the Python domain package at `packages/python/domain`.
+- Keep the domain import package at `packages/python/domain/src/{name_underscore}_domain` so imports read as `from {name_underscore}_domain ...`.
+- Keep optional Rust engine packages at `packages/python/{name}-engine` unless the product contract changes.
+
+## Python Naming Rule
+
+- Use kebab-case for filesystem roots such as `apps/{name}-api`.
+- Use snake_case for the import package inside `src/`, for example `apps/{name}-api/src/{name}_api`.
+- Apply the same rule to the domain package: keep the root directory `packages/python/domain`, but keep the import package at `src/{name_underscore}_domain`.
+- Keep the Python package name in `pyproject.toml` kebab-case.
+- Add a `tests/` directory for generated Python apps and libraries.
+
+## Node And Storybook Expectations
+
+- Generate React app and library projects in a way that preserves the expected Nx command surface.
+- The web app should expose at least `serve`, `build`, `lint`, `test`, and `typecheck` when those capabilities exist in the generated project.
+- The UI library should expose at least `build`, `lint`, `test`, and `typecheck`.
+- Keep Storybook as a dedicated host project at `packages/node/sb`; do not silently repurpose the UI library as the Storybook project.
+
+## Python Expectations
+
+- Generated Python projects should use `src/` and `tests/` layout.
+- Keep Python projects registered in `[tool.uv.workspace].members`.
+- Use Nx `project.json` files to expose Python tasks through `nx:run-commands`.
+- Ensure generated API code only imports scaffolds that actually exist in the generated domain package.
+
+## Alembic And Nx Migrations
+
+- For Python services that own schema changes, add Alembic to the package that owns the domain models and expose it through an Nx target.
+- The standard domain layout is `packages/python/domain/alembic.ini` plus `packages/python/domain/migrations/`.
+- The standard Nx target shape is a `migrate` target on the domain project that runs `uv run alembic -c packages/python/domain/alembic.ini` from the workspace root.
+- Run migration commands from the workspace root with the `--` separator so Alembic receives its own arguments.
+
+```sh
+npx nx run domain:migrate -- revision --autogenerate -m "{number}_a_descriptive_message"
+npx nx run domain:migrate -- upgrade head
+npx nx run domain:migrate -- downgrade -1
+```
+
+- Alembic autogeneration depends on model discovery, so make sure the domain model registry imports newly added entity modules.
+
+## Dependency And Membership Rules
+
+- When one workspace Python package depends on another, declare it in dependencies and mirror it in `[tool.uv.sources]` with `workspace = true`.
+- After creating or modifying workspace packages, keep root UV workspace membership current.
+- Do not document `uv sync --all-packages` or Nx commands unless the generated workspace can actually run them.
+
+## Review Checklist
+
+- Root files match the generated command surface: `pyproject.toml`, `nx.json`, `package.json`, `.pre-commit-config.yaml`.
+- Project roots and import package names follow the kebab-case and snake_case rules.
+- Python projects have both `src/` and `tests/`.
+- The domain import package remains `src/{name_underscore}_domain`.
+- Storybook remains hosted in `packages/node/sb`.
+- Workspace members and workspace dependency sources are complete.
+- Generated instructions, checks, and scaffolds refer to the current contract rather than stale paths.

rpr/scaffolds/instructions/tooling-setup.instructions.md

@@ -0,0 +1,97 @@
+---
+applyTo: "pyproject.toml,nx.json,.pre-commit-config.yaml,package.json,apps/*/project.json,packages/**/project.json,apps/*/eslint.config.mjs,packages/**/eslint.config.mjs,packages/python/*-engine/Cargo.toml"
+description: "Use when setting up or modifying Ruff, TypeScript linting, ESLint, Prettier, cargo fmt, Clippy, or pre-commit in an RPR workspace"
+---
+
+# Tooling Setup
+
+Use this guidance when editing workspace tooling files or bootstrapping linting, formatting, and pre-commit automation.
+
+## First Rule
+
+- Match the existing workspace toolchain before adding anything new.
+- Keep docs, Nx targets, package dependencies, and pre-commit hooks consistent with each other.
+- Do not document commands that the workspace cannot actually run.
+
+## Python Baseline
+
+- Use Ruff for Python linting and formatting.
+- Keep Ruff configuration in the root `pyproject.toml`.
+- Prefer `uv run ruff check` for linting and `uv run ruff format` for formatting.
+- If the workspace already has a Ruff config, extend it rather than replacing it with a different rule set.
+- If bootstrapping from the current RPR defaults, preserve the existing generated baseline unless the task explicitly asks for different rules.
+
+## TypeScript and React Baseline
+
+- In the current RPR generator, the default `lint` target for Node and React projects is `npx eslint .`.
+- Keep `typecheck` as a separate target that runs `npx tsc --noEmit`.
+- Use ESLint flat config and the Nx plugin entry `@nx/eslint/plugin` in `nx.json`.
+- Treat Prettier as the default formatter for Node-side code and keep it complementary to ESLint.
+
+Valid `nx.json` plugin example:
+
+```json
+{
+  "plugins": [
+    {
+      "plugin": "@nx/eslint/plugin",
+      "options": {
+        "targetName": "lint"
+      }
+    }
+  ]
+}
+```
+
+## Rust Baseline
+
+- Use `cargo fmt --check` for formatting validation.
+- Use `cargo clippy --all-targets --all-features -- -D warnings` for linting.
+- In RPR-generated engine packages, prefer the existing Nx targets `engine:format` and `engine:lint`.
+
+## Pre-commit Rules
+
+- Keep `.pre-commit-config.yaml` syntactically valid YAML.
+- Define one hook per command. Do not reuse a single hook entry for two commands.
+- Hook ids, documented manual run commands, and actual entries must match exactly.
+- Prefer commands the workspace already uses in `project.json`, `package.json`, or root scripts.
+- When bootstrapping a fresh RPR workspace, scaffold `eslint` and `prettier` hooks with the matching config files.
+
+Valid local hook example aligned with the current RPR defaults:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: Ruff format
+        entry: uv run ruff format .
+        language: system
+        pass_filenames: false
+
+      - id: ruff-lint
+        name: Ruff lint
+        entry: uv run ruff check . --fix
+        language: system
+        pass_filenames: false
+
+      - id: prettier
+        name: Prettier
+        entry: npx prettier --write .
+        language: system
+        pass_filenames: false
+
+      - id: eslint
+        name: ESLint
+        entry: npx eslint . --ext .js,.jsx,.ts,.tsx --fix
+        language: system
+        pass_filenames: false
+```
+
+## Consistency Checks
+
+- Use `package.json`, not `packages.json`.
+- If linting uses ESLint, keep a separate `typecheck` target for `npx tsc --noEmit`.
+- If you introduce a hook named `eslint` or `prettier`, define that hook explicitly.
+- If you document ESLint, ensure the package install, config format, Nx integration, and manual commands all match.
+- If a long-form guide conflicts with the generated project defaults, update the guide or the generator so they agree.

rpr/scaffolds/instructions/tooling.instructions.md

@@ -0,0 +1,42 @@
+---
+applyTo: "**"
+description: "Workspace tooling conventions for linting, formatting, and pre-commit"
+---
+
+# Tooling Conventions
+
+Use the workspace's existing linting, formatting, and pre-commit setup when it already exists. Do not introduce a second parallel toolchain.
+
+## Python
+
+- Use Ruff for Python linting and formatting.
+- Keep Ruff configuration in the root `pyproject.toml` under `[tool.ruff]`.
+- Prefer workspace commands such as `uv run ruff check` and `uv run ruff format`.
+- If the project already pins Ruff in dependencies, keep it there. Do not rely on undocumented cache behavior as the only installation path.
+
+## TypeScript and React
+
+- In RPR-generated workspaces, use ESLint flat config for JavaScript and TypeScript linting, Prettier for formatting, and `npx tsc --noEmit` as a separate typecheck target.
+- Keep the root `nx.json` ESLint plugin entry and project-local `eslint.config.mjs` files aligned.
+- Extend existing flat-config files instead of introducing a different ESLint config format.
+- Keep `lint`, `format`, and `typecheck` responsibilities separate. Do not use TypeScript typechecking as a substitute for ESLint.
+
+## Rust
+
+- Use `cargo fmt --check` for formatting validation.
+- Use `cargo clippy --all-targets --all-features -- -D warnings` for linting.
+- Prefer existing Nx targets such as `engine:format` and `engine:lint` when they exist.
+
+## Pre-commit
+
+- Pre-commit hooks must call commands that already exist in the workspace.
+- Keep hook ids, entries, and manual run examples aligned. Do not document a hook name that is not defined.
+- Prefer running workspace-level commands through `uv run`, `npx`, `npx nx`, or existing package-manager scripts rather than ad hoc shell fragments.
+- When the default Node tooling is scaffolded, keep `eslint` and `prettier` hooks aligned with the generated config files.
+- Ensure YAML examples are syntactically valid before adding them to shared docs or instructions.
+
+## Change Discipline
+
+- Reuse existing root config files such as `pyproject.toml`, `nx.json`, `eslint.config.mjs`, and `.pre-commit-config.yaml` instead of creating duplicates.
+- When a task is specifically to bootstrap tooling from scratch, keep the configuration consistent across docs, generated targets, and hook examples.
+- Use `tooling-setup.instructions.md` for file-level guidance when editing root tooling config files.

rpr/scaffolds/js_special_files/fetch.service.md

@@ -0,0 +1,222 @@
+## Internal Template Source: API Service
+
+Target path: `/packages/node/{name}-ui/src/services/base/api.service.ts`
+
+This markdown file is an internal generator source for `rpr add template fetch_service`. It is not synced project instruction guidance.
+
+Keep the first TypeScript block as the complete generated file. `src/rpr/commands/add.py` extracts the first matching fenced block for this template.
+
+```ts
+export type ApiError = {
+  message: string;
+  status: number;
+  details?: unknown;
+  response: Response;
+};
+
+declare const getToken: () => Promise<string | null>;
+declare const globalErrorHandler: ((error: ApiError) => void) | undefined;
+
+const buildUrl = (
+  endpoint: string,
+  params?: Record<string, unknown>,
+): string => {
+  // 1) Resolve full URL from base config
+  // 2) Append query parameters if present
+  return endpoint;
+};
+
+const createRequestInit = async (
+  method: string,
+  initHeaders?: HeadersInit,
+  body?: BodyInit,
+): Promise<RequestInit> => {
+  const headers = new Headers({
+    Accept: "application/json",
+    ...initHeaders,
+  });
+
+  if (body && !headers.has("Content-Type")) {
+    headers.set("Content-Type", "application/json");
+  }
+
+  if (!headers.has("Authorization")) {
+    const token = await getToken();
+    if (token) {
+      headers.set("Authorization", `Bearer ${token}`);
+    }
+  }
+
+  const requestInit: RequestInit = {
+    method,
+    headers,
+  };
+
+  if (body) {
+    requestInit.body = body;
+  }
+
+  return requestInit;
+};
+
+const onApi401 = async (
+  _response: Response,
+  error: ApiError,
+): Promise<never> => {
+  // Handle 401 Unauthorized error
+  return Promise.reject(error);
+};
+
+const handleError = async (response: Response): Promise<ApiError> => {
+  let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+  let errorDetails = response.statusText;
+
+  try {
+    const contentType = response.headers.get("content-type");
+
+    if (contentType && contentType.includes("application/json")) {
+      const errorData = (await response.json()) as {
+        message?: string;
+        detail?: string;
+      };
+
+      errorMessage = errorData.message || errorData.detail || errorMessage;
+      errorDetails = errorData;
+    } else {
+      const textError = await response.text();
+      if (textError) {
+        errorMessage = textError;
+        errorDetails = textError;
+      }
+    }
+  } catch (error: unknown) {
+    console.error("Failed to parse default message", error);
+  }
+
+  return {
+    message: errorMessage,
+    status: response.status,
+    details: errorDetails,
+    response,
+  };
+};
+
+const handleResponse = async <T>(response: Response): Promise<T> => {
+  if (!response.ok) {
+    const error = await handleError(response);
+    if (response.status === 401) {
+      return await onApi401(response, error);
+    }
+
+    // If you have a way to handle error, like a snackbar
+    if (globalErrorHandler) {
+      globalErrorHandler(error);
+    }
+
+    throw error;
+  }
+
+  if (response.status === 204) return undefined as T;
+
+  const contentType = response.headers.get("content-type");
+  if (contentType && contentType.includes("application/json")) {
+    return await response.json();
+  }
+
+  if (contentType && contentType.includes("image/")) {
+    const blob = await response.blob();
+    return blob as unknown as T;
+  }
+
+  const text = await response.text();
+  return text as unknown as T;
+};
+
+export const apiService = {
+  async get<T>(
+    endpoint: string,
+    params?: Record<string, unknown>,
+    headers?: HeadersInit,
+  ): Promise<T> {
+    const url = buildUrl(endpoint, params);
+    const requestInit = await createRequestInit("GET", headers);
+    const response = await fetch(url, requestInit);
+    return handleResponse<T>(response);
+  },
+
+  async post<T>(
+    endpoint: string,
+    data?: unknown,
+    headers?: HeadersInit,
+  ): Promise<T> {
+    const url = buildUrl(endpoint);
+    const requestInit = await createRequestInit(
+      "POST",
+      headers,
+      data ? JSON.stringify(data) : undefined,
+    );
+    const response = await fetch(url, requestInit);
+    return handleResponse<T>(response);
+  },
+
+  async put<T>(
+    endpoint: string,
+    data?: unknown,
+    headers?: HeadersInit,
+  ): Promise<T> {
+    const url = buildUrl(endpoint);
+    const requestInit = await createRequestInit(
+      "PUT",
+      headers,
+      data ? JSON.stringify(data) : undefined,
+    );
+    const response = await fetch(url, requestInit);
+    return handleResponse<T>(response);
+  },
+
+  async delete<T>(endpoint: string, headers?: HeadersInit): Promise<T> {
+    const url = buildUrl(endpoint);
+    const requestInit = await createRequestInit("DELETE", headers);
+    const response = await fetch(url, requestInit);
+    return handleResponse<T>(response);
+  },
+
+  async patch<T>(
+    endpoint: string,
+    data?: unknown,
+    headers?: HeadersInit,
+  ): Promise<T> {
+    const url = buildUrl(endpoint);
+    const requestInit = await createRequestInit(
+      "PATCH",
+      headers,
+      data ? JSON.stringify(data) : undefined,
+    );
+    const response = await fetch(url, requestInit);
+    return handleResponse<T>(response);
+  },
+};
+```
+
+## What This Template Owns
+
+- Shared request setup, including default headers and bearer-token injection
+- Centralized API error parsing
+- Standard response handling for JSON, text, blobs, and `204 No Content`
+- Thin HTTP helpers that feature-specific services can reuse
+
+## Integration Notes
+
+- Replace `buildUrl` with the project's actual API base-URL logic.
+- Provide a real `getToken()` implementation or wire authentication through the app's existing auth boundary.
+- Connect `globalErrorHandler` to the project's notification or error-reporting path if one exists.
+- Keep domain-specific services small. They should call `apiService`, not duplicate fetch behavior.
+- Synced target-facing guidance belongs in `frontend.instructions.md` and should reference `.github/scaffolds/frontend/api.service.ts`.
+
+## Usage
+
+```ts
+export const UserService = {
+  getUsers: () => apiService.get<User[]>(`/users`),
+};
+```

rpr/scaffolds/js_special_files/sticky-navigation.md

@@ -0,0 +1,164 @@
+## Internal Template Source: useStateNavigation
+
+Target path: `/packages/node/{name}-ui/src/hooks/useStateNavigation.ts`
+
+This markdown file is an internal generator source for `rpr add template sticky_navigation`. It is not synced project instruction guidance.
+
+Keep the first TypeScript block as the complete generated file. `src/rpr/commands/add.py` extracts the first matching fenced block for this template.
+
+```ts
+import { useCallback, useLayoutEffect, useState } from "react";
+
+type NavigationStateChangeDetail = {
+  property: string;
+  newValue: string | null;
+};
+
+type SetNavigationValueOptions = {
+  replace?: boolean;
+};
+
+type SetNavigationValue = (
+  newValue: string | null,
+  options?: SetNavigationValueOptions,
+) => void;
+
+const normalizeValue = (value?: string | null): string => value?.trim() ?? "";
+
+const getInitialValue = (property: string, defaultValue: string): string => {
+  const currentParams = new URLSearchParams(window.location.search);
+  const normalizedDefaultValue = normalizeValue(defaultValue);
+
+  return normalizeValue(currentParams.get(property)) || normalizedDefaultValue;
+};
+
+const buildUrlFromValue = (property: string, value?: string | null): string => {
+  const normalizedValue = normalizeValue(value);
+  const currentParams = new URLSearchParams(window.location.search);
+
+  if (!normalizedValue) {
+    currentParams.delete(property);
+  } else {
+    currentParams.set(property, normalizedValue);
+  }
+
+  const newSearch = currentParams.toString();
+
+  return newSearch
+    ? `${window.location.pathname}?${newSearch}${window.location.hash}`
+    : `${window.location.pathname}${window.location.hash}`;
+};
+
+export const useStateNavigation = (
+  property: string,
+  defaultValue = "",
+): readonly [string, SetNavigationValue] => {
+  const normalizedDefaultValue = normalizeValue(defaultValue);
+
+  const [value, setValueState] = useState(() =>
+    getInitialValue(property, normalizedDefaultValue),
+  );
+
+  const syncValueFromUrl = useCallback(() => {
+    const nextValue = getInitialValue(property, normalizedDefaultValue);
+
+    setValueState((previousValue) =>
+      previousValue === nextValue ? previousValue : nextValue,
+    );
+  }, [property, normalizedDefaultValue]);
+
+  useLayoutEffect(() => {
+    syncValueFromUrl();
+  }, [syncValueFromUrl]);
+
+  useLayoutEffect(() => {
+    const controller = new AbortController();
+
+    const handleNavigationStateChange = (event: Event) => {
+      const customEvent = event as CustomEvent<NavigationStateChangeDetail>;
+      const { property: changedProperty, newValue } = customEvent.detail;
+
+      if (changedProperty !== property) {
+        return;
+      }
+
+      const normalizedValue = normalizeValue(newValue);
+
+      setValueState((previousValue) =>
+        previousValue === normalizedValue ? previousValue : normalizedValue,
+      );
+    };
+
+    window.addEventListener(
+      "NavigationStateChange",
+      handleNavigationStateChange,
+      { signal: controller.signal },
+    );
+    window.addEventListener("popstate", syncValueFromUrl, {
+      signal: controller.signal,
+    });
+
+    return () => {
+      controller.abort();
+    };
+  }, [property, syncValueFromUrl]);
+
+  const setValue = useCallback<SetNavigationValue>(
+    (newValue, options) => {
+      const normalizedValue = normalizeValue(newValue);
+      const newUrl = buildUrlFromValue(property, normalizedValue);
+      const currentUrl = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+
+      if (newUrl === currentUrl) {
+        return;
+      }
+
+      if (options?.replace) {
+        window.history.replaceState(null, "", newUrl);
+      } else {
+        window.history.pushState(null, "", newUrl);
+      }
+
+      window.dispatchEvent(
+        new CustomEvent<NavigationStateChangeDetail>("NavigationStateChange", {
+          detail: {
+            property,
+            newValue: normalizedValue || null,
+          },
+        }),
+      );
+    },
+    [property],
+  );
+
+  useLayoutEffect(() => {
+    if (!normalizedDefaultValue) {
+      return;
+    }
+
+    const urlValue = normalizeValue(
+      new URLSearchParams(window.location.search).get(property),
+    );
+
+    if (urlValue) {
+      return;
+    }
+
+    setValue(normalizedDefaultValue, { replace: true });
+  }, [normalizedDefaultValue, property, setValue]);
+
+  return [value, setValue] as const;
+};
+```
+
+## Why This Uses `useLayoutEffect`
+
+Use `useLayoutEffect` here because URL-to-state synchronization and listener registration should happen before paint. That avoids stale UI during mount and reduces the chance of missing navigation events dispatched immediately after render.
+
+## Usage Rules
+
+- Use this hook only in UI-layer React code.
+- Pass the default value into the hook. Do not initialize state by calling `setValue` during mount.
+- Use one query-string property per independently controlled state value.
+- Keep stored values string-based. If a feature needs richer state, encode and decode it explicitly at the edge.
+- Synced target-facing guidance belongs in `frontend.instructions.md` and should reference `.github/scaffolds/frontend/useStateNavigation.ts`.