@ai-support-agent/cli 0.1.32-beta.1 → 0.1.33-beta.0

package/dist/plugin/rules/documentation/docs-site.md

@@ -0,0 +1,60 @@
+# Documentation Site Conventions (Docusaurus / i18n)
+
+The documentation site standardizes on Docusaurus and supports switching between locales. For concrete build and integration steps and templates, see the docs-site skill. This document defines what must be upheld.
+
+## i18n (multiple languages)
+
+- Support exactly two locales: a **default** locale and a secondary locale (e.g., `en` as default, `ja` as secondary — pick and declare the pairing per project).
+- **Hand-written guides and conceptual pages must exist in both locales.** Any PR that updates the source-language page must also update the translation.
+- If a translation unavoidably lags behind, add an "untranslated" notice at the top of the translated page (including the date the source was last updated). This notice is something the update-docs workflow should detect.
+- Auto-generated reference pages (see below) only need to exist in the default locale — this is a deliberate decision to keep translation-sync costs down.
+
+## Page categories and generation method
+
+| Page type | Method | i18n |
+|---|---|---|
+| Guides, concepts, tutorials | Hand-written | Both languages required |
+| NestJS API reference | Auto-generated from OpenAPI (no hand-transcription) | Default locale only |
+| TypeScript library function reference | Recommended: auto-generated from TypeDoc | Default locale only |
+| Python / PHP function reference | Hand-written from a template, with a consistency check | Default locale only |
+
+## Sidebar organization (structuring the function list)
+
+- Organize function references in the sidebar as a **category (module / functional area) → function name** hierarchy.
+- Auto-generated pages use the sidebar the plugin outputs; hand-written pages must always be registered in the category definitions in `sidebars.js` — never leave a page unregistered (i.e., undiscoverable from the index).
+- Order categories by usage frequency and learning path, not mechanically by alphabetical order.
+
+## Required sections on a function detail page (the canonical template)
+
+Whether hand-written or auto-generated, every function detail page must include:
+
+1. **Overview** — 1–3 sentences on what the function is for.
+2. **Signature** — the declaration, matching the implementation exactly.
+3. **Parameters table** — name / type / required / description (**name and required-ness must match the implementation character-for-character**).
+4. **Output (return value)** — type and content, including how it varies by condition if applicable.
+5. **Errors** — exceptions thrown or error codes returned, and the condition that triggers each.
+6. **Usage example** — a minimal, working code snippet.
+7. **Tests** — a link to the relevant test file (optional but recommended).
+
+## Keeping docs in sync with source (verification convention for transcribed content)
+
+- **Hand-written reference pages must include a `source` key in frontmatter.**
+
+  ```yaml
+  ---
+  source: src/services/estimateApproval.ts#requiresDirectorApproval
+  ---
+  ```
+
+- `source` is the machine-readable anchor for consistency checking. The update-docs workflow uses this key as a starting point to read the implementation and verify:
+  - **Incorrect** function or parameter names (mismatched against the implementation)
+  - **Missing** parameters or error entries (present in the implementation but absent from the page)
+  - **Stale leftovers** (present on the page but removed from the implementation)
+- The page must always describe the implementation **as it actually behaves**. If you believe the implementation itself is wrong, propose fixing the implementation — don't just edit the page to match a mistake.
+
+## Linking to tests
+
+- Use **repository-absolute URLs anchored to the default branch** (e.g., `https://github.com/<org>/<repo>/blob/main/src/services/estimateApproval.spec.ts`).
+- Don't use commit-SHA-pinned links — they're costly to maintain and inevitably go stale.
+- For linking from auto-generated TypeDoc pages, use the TSDoc `@see` tag.
+- The update-docs workflow verifies that linked files exist.

package/dist/plugin/rules/documentation/source-docs.md

@@ -0,0 +1,89 @@
+# In-Source Documentation Conventions
+
+Building on the commenting principles in `rules/common/coding-guidelines.md`, this document defines the format and language for doc comments.
+
+## Declaring the designated language
+
+- Declare your documentation language in each project's CLAUDE.md, using a section like this:
+
+  ```markdown
+  ## Documentation conventions
+  - Designated language: English | Japanese | Bilingual
+  - Adopted conventions: list which files under rules/documentation/ this project follows (e.g., source-docs, api-docs, docs-site, test-docs)
+  ```
+
+- **If undeclared, the default is English** (adjust this default to whatever fits your project/organization).
+- Public libraries and repositories with external collaborators should favor "English" or "Bilingual."
+- Reviewers should only flag mismatches against the *declared* language. If you spot mixed languages in a project with no declaration, propose adding the declaration rather than flagging the mix itself.
+
+## General principles
+
+- Doc comments are required only for **public APIs, exported functions, and shared library code** — not for internal helpers whose name and signature are already self-explanatory.
+- Required elements: a one-sentence summary, parameter descriptions, return value description, and any exceptions thrown (if applicable).
+- Favor explaining "why this exists / what constraints apply" over "what it does." Don't write a comment that just restates the implementation.
+- Don't repeat information the signature (type declarations) already conveys.
+
+## Format by language
+
+### TypeScript — TSDoc
+
+```typescript
+/**
+ * Determines whether the estimate amount exceeds the approval threshold.
+ *
+ * @param estimate - The estimate to evaluate. Must already be finalized.
+ * @param threshold - The threshold (pre-tax, in the base currency). Falls back to the system setting if omitted.
+ * @returns true if the amount exceeds the threshold
+ * @throws {EstimateNotFixedError} if the estimate has not been finalized
+ * @see tests/services/estimateApproval.spec.ts
+ */
+```
+
+- Use `@param` / `@returns` / `@throws`. Let the signature carry the type information — don't restate types in the comment.
+- Use `@see` to reference related tests or functions (this also becomes a link on the documentation site).
+
+### Python — docstrings (Google style)
+
+```python
+def calculate_invoice_total(invoice_id: int) -> Decimal:
+    """Calculates the total amount for an invoice.
+
+    Args:
+        invoice_id: The target invoice ID. Must already be finalized.
+
+    Returns:
+        The tax-inclusive total amount.
+
+    Raises:
+        InvoiceNotFoundError: If the invoice does not exist.
+    """
+```
+
+- Use Google style (Args / Returns / Raises) as the default. If a project already uses NumPy or reST style, follow the existing convention instead.
+
+### PHP — PHPDoc
+
+```php
+/**
+ * Confirms an order and allocates inventory for it.
+ *
+ * @param Order $order The order to confirm. Must be in draft status.
+ * @return Order The confirmed order
+ * @throws InventoryShortageException If there is insufficient inventory.
+ */
+```
+
+- Omit type annotations that duplicate native type declarations (parameter and return types). Don't write a bare `@param Order $order` line with no description.
+
+## Bilingual format
+
+When the designated language is "Bilingual," write the primary language first, followed by the secondary language, within the same block.
+
+```typescript
+/**
+ * Determines whether the estimate amount exceeds the approval threshold.
+ * (secondary-language translation of the same sentence)
+ */
+```
+
+- The summary is required in both languages. Parameter descriptions are required in the primary language and optional in the secondary language, to keep the maintenance burden reasonable.

package/dist/plugin/rules/documentation/test-docs.md

@@ -0,0 +1,39 @@
+# Test Documentation Conventions
+
+Tests are a specification. The goal is that reading the list of test names alone gives you a list of the spec's requirements, and reading a test's body gives you the detail (what it covers and why).
+
+## Writing describe / it blocks
+
+- **describe**: names the subject under test (class, function, or endpoint). Use nested describes to represent different scenarios ("when inventory is insufficient," "when the user has admin privileges").
+- **it / test**: write a **complete specification sentence that includes an observable outcome**, in the project's designated language.
+
+```typescript
+describe('EstimateApprovalService.approve', () => {
+  describe('when the estimate amount exceeds $10,000', () => {
+    it('does not become approved until director approval is complete', () => { ... });
+    it('throws PendingDirectorApprovalError when only the manager has approved', () => { ... });
+  });
+});
+```
+
+- Forbidden names: uninformative labels like "happy path," "error case 1," "test1," "works," "OK" — anything that doesn't convey the spec on its own.
+- **Whatever outcome the test name claims must actually be asserted in the body.** A name like "throws an exception" with no assertion verifying the exception is a mismatch that the update-docs workflow and code review should catch.
+
+## Structuring the test body
+
+- Separate Arrange / Act / Assert with blank lines so the flow is easy to follow.
+- For complex setup, add a comment explaining what scenario is being constructed.
+- Annotate meaningful test data with its rationale (e.g., `1_000_001 // one above the $10,000 threshold boundary`). Don't annotate values that have no particular significance.
+
+## Conventions by stack
+
+| Stack | Test naming | Notes |
+|---|---|---|
+| Jest / Vitest / Playwright | describe + it (as above) | Nest with `test.describe` where helpful |
+| pytest | Test function name (e.g., `test_requires_director_approval_above_threshold`, in the designated language if appropriate) | For complex cases, put the summary and intent in a docstring |
+| PHPUnit | Test method name | The `@testdox` annotation can spell out the spec sentence; `#[TestDox('throws an exception when inventory is insufficient')]` is recommended |
+
+## Scope of application
+
+- All new tests must follow this convention.
+- Rename existing tests opportunistically, as part of a change that already touches them — a rename-only bulk change isn't worth the review cost on its own.

package/dist/plugin/rules/logging/logging-rules.md

@@ -0,0 +1,83 @@
+# Logging Conventions
+
+Goal: make it possible for both humans and AI to complete debugging **by reading only the source comments and the logs**. The standard is that logs alone should let you reconstruct "which user's, which request's, which function, with what input, passed through and failed where."
+
+## Adoption and cost tuning
+
+- Projects adopting this convention should add `logging` to the "adopted conventions" list in the "## Documentation conventions" section of their CLAUDE.md.
+- Log volume translates directly into cost, so **control output level via an environment variable** and tune it per project (typical default: INFO in production, DEBUG in development/investigation as a debug mode).
+- For high-traffic code paths, consider sampling DEBUG output (emit only a fraction of events). Document any such tuning in CLAUDE.md.
+
+## Basics
+
+- **Structured logging (JSON) is the standard.** Emit a `message` plus fields — don't embed information via string concatenation.
+- Field names are **full English words in snake_case, never abbreviated** (`request_id`, not `req_id`; `user_id`, not `uid`; also `duration_ms`, `function_name`).
+- Write messages in the project's designated language (same as the documentation convention; default to English if undeclared). Field names are always in English.
+
+### Choosing a log level
+
+| Level | Use |
+|---|---|
+| ERROR | A failure that requires action. Always include the exception, correlation ID, and the ID of the affected resource. |
+| WARN | An anomaly that self-recovered, a retry, approaching a threshold — anything worth monitoring. |
+| INFO | Business events (start/completion of order confirmation, invoice issuance, etc.; state transitions). The standard production level. |
+| DEBUG | For investigation: function start/end, inputs/outputs, and the data behind branching decisions. |
+
+## Correlation IDs (end-to-end tracing)
+
+To let you trace all logs from a single request across the system, **attach the following to every log entry automatically** — never pass them manually at each call site.
+
+- `request_id`: capture the `X-Request-Id` header at the request entry point (generate one if absent), set it in the logging context, and echo it back in the response header.
+- `user_id` (set after authentication), `tenant_code` (in multi-tenant systems, also useful for verifying tenant isolation).
+- `trace_id`: if you have AWS X-Ray (or an equivalent tracing system) enabled, include the trace ID as well, so logs and traces can be cross-referenced (for Lambda, enabling active tracing propagates the header automatically).
+- **Propagation into async work**: when enqueuing a job, include `request_id` in the message and restore it into the logging context on the worker side. For batch-originated processing, generate a `job_id` per execution unit.
+
+### Implementing context propagation, by stack
+
+| Stack | Implementation |
+|---|---|
+| NestJS | nestjs-pino + AsyncLocalStorage (set request_id / user_id in middleware). On Lambda, AWS Lambda Powertools Logger + `injectLambdaContext`. |
+| Django / Flask | structlog + contextvars. Bind in middleware; propagate to Celery etc. via headers. |
+| Laravel | Set Log Context (`Context::add()`) in middleware. Propagate to queued jobs via Context dehydration. |
+| CakePHP | Attach common fields via a Monolog Processor. |
+
+## Debug mode (DEBUG level)
+
+- **Log the start and end of each function**: `function_name`, the input (INPUT) at start, and the output (OUTPUT) plus `duration_ms` at end.
+- Apply this to public methods in the service/use-case layer by default; skip trivial getters and one-line utilities.
+- Don't scatter this by hand — implement it cross-cuttingly (decorators, interceptors, etc.).
+
+```typescript
+// NestJS example: a method decorator that logs start/end/input/output at DEBUG level
+@LogExecution() // implementation lives in a shared project library
+async approveEstimate(input: ApproveEstimateInput): Promise<EstimateResult> { ... }
+// DEBUG: {"message":"function start","function_name":"approveEstimate","input":{...},"request_id":"..."}
+// DEBUG: {"message":"function end","function_name":"approveEstimate","output":{...},"duration_ms":42,"request_id":"..."}
+```
+
+### Masking (required even at DEBUG level)
+
+- Never log passwords, tokens, API keys, or personal information (name, email, address, etc., per your project's definition) — **even at DEBUG level**. Route these through a shared masking function.
+- Truncate large payloads (file contents, large arrays) down to a count/size summary.
+
+## Recording errors
+
+- Every ERROR log must include: the exception object (with stack trace), `request_id`, the ID of the affected resource (e.g., `order_id`), and what operation was being attempted.
+- **If the project uses Sentry, capture unhandled exceptions there too.**
+  - Send them via a single global exception handler (a NestJS exception filter, or the equivalent in Django/Laravel) rather than manually capturing at each call site. (Rule of thumb: only manually capture "handled" exceptions — ones that don't propagate to the caller — when they're operationally worth knowing about.)
+  - Set `request_id` / `user_id` as Sentry tags/context so they can be cross-referenced with logs and traces.
+  - Don't report exceptions that were caught and handled as part of normal flow — that's just noise and duplicate alerting.
+- The discipline of error handling itself (never swallow, preserve the cause) follows the standards in rules/common and the silent-failure-hunter criteria.
+
+## Checklist: logs an AI can debug from
+
+Confirm new feature logging design satisfies the following:
+
+- [ ] Every log for a given request (including async work) can be retrieved by `request_id`.
+- [ ] The retrieved logs alone reveal the order of functions traversed and their inputs/outputs (at DEBUG level).
+- [ ] On failure, the ERROR log has everything: where it happened, what was being attempted, what went wrong, and what resource was affected.
+- [ ] Read together with the source comments (constraints, intent), you can form a root-cause hypothesis without running the code.
+
+## Naming and clarity (a prerequisite shared with logging)
+
+Readable logs depend on readable naming in the implementation. Follow the naming rules in `rules/common/coding-guidelines.md` (**avoid abbreviations, use full English words; name functions so they read as a sentence describing what they do**). Ideally, `function_name` alone should read like a spec.

package/dist/plugin/rules/php/coding-rules.md

@@ -0,0 +1,40 @@
+# PHP Coding Rules
+
+For language-agnostic rules, see `rules/common/coding-guidelines.md`. This document covers only PHP-specific rules.
+
+## Language and types
+
+- Add `declare(strict_types=1)` to every new file (except views such as Blade templates).
+- Declare parameter and return types on public methods. Reserve `mixed` for cases that genuinely can't be expressed as a union type.
+- Mark constructor-promoted properties `readonly` when they're never reassigned.
+- Leave formatting to Pint / PHP CS Fixer (PSR-12) — don't debate formatting in review.
+- Never commit `var_dump()` / `dd()` / `dump()` calls.
+
+## Error handling
+
+- Empty `catch (\Exception $e) {}` blocks are forbidden. Log the error and handle it (propagate, retry, notify).
+- When re-throwing, preserve the cause: `throw new XxxException('...', previous: $e)`.
+- Don't ignore the return value of APIs that return `false` on failure (e.g., `save()`).
+
+## Laravel
+
+- Define `$fillable` on every model. `$guarded = []` is forbidden.
+- Don't pass `$request->all()` directly into a save. Define a FormRequest and use `$request->validated()`; implement `authorize()` too.
+- Use `with()` / `load()` for eager loading whenever you access a relation in a loop.
+- Any user input passed into `DB::raw()` / `whereRaw()` must use parameter binding.
+- Never use Blade's `{!! !!}` on user-supplied data. If you must, comment the sanitization rationale.
+- Implement `failed()` on queued jobs and configure `$tries` / `$backoff`. Write jobs to be idempotent.
+- Authorize via `auth` middleware plus `Gate` / `Policy` — don't rely on hiding UI elements alone.
+- Define `$casts` for date, JSON, and boolean columns.
+
+## CakePHP
+
+- Never set `'*' => true` in an Entity's `$_accessible`. Explicitly list which fields allow mass assignment.
+- Use `contain()` when accessing related data in a loop.
+- Use `validationDefault()` for input format validation, and `buildRules()` for domain rules like uniqueness/existence checks — keep the two separate.
+- Always check the return value of `save()`.
+- Never interpolate variables directly into query conditions (`"field = '$value'"`). Use array conditions or parameter binding instead.
+
+## Documentation
+
+- For PHPDoc format and comment language, see `rules/documentation/`.

package/dist/plugin/rules/python/coding-rules.md

@@ -0,0 +1,40 @@
+# Python Coding Rules
+
+For language-agnostic rules, see `rules/common/coding-guidelines.md`. This document covers only Python-specific rules.
+
+## Type hints and syntax
+
+- Add type hints to public functions. Reserve `Any` for receiving data at external boundaries — narrow it to a concrete type internally.
+- Make optionality explicit with `X | None` (3.10+) or `Optional[X]`.
+- Mutable default arguments (`def f(items=[])`) are forbidden. Default to `None` and construct the value inside the function.
+- Never compare against `None` with `==`. Use `is None` / `is not None`.
+- Don't shadow builtin names (`list`, `dict`, `id`, `type`).
+- Leave formatting and import ordering to ruff / black — don't debate them in review.
+
+## Error handling
+
+- Bare `except:` and `except Exception: pass` are forbidden. Catch specific exceptions and handle them (log and propagate, retry, or notify).
+- Manage files, connections, and locks with `with` (context managers).
+- When re-raising, preserve the cause with `raise ... from e`.
+
+## Django
+
+- Always use `select_related` (FK/OneToOne) or `prefetch_related` (M2M/reverse relations) when accessing related objects in a loop.
+- Never do a read-increment-save cycle for counters; update atomically with an `F()` expression.
+- Wrap multiple writes in `transaction.atomic()`.
+- Every model change needs a migration; drop columns via a two-phase deploy (make nullable → remove references → drop the column in a later release).
+- DRF: `fields = '__all__'` on a Serializer is forbidden. List fields explicitly and set `read_only_fields`. List endpoints must be paginated.
+- Use `save(update_fields=[...])` for partial updates so you don't clobber concurrent writes.
+- Don't use signals for intra-app model-to-model coordination; prefer explicit calls from the service layer.
+
+## Flask
+
+- Use the application factory pattern (`create_app()`). Don't instantiate `app` at module level.
+- Split routes into feature-scoped Blueprints.
+- Validate `request.json` / `request.args` with marshmallow or pydantic before use.
+- Keep request-scoped state in `g` and configuration in `app.config`. Don't share state through mutable module-level globals.
+- Ensure `db.session.commit()` failures trigger a `rollback()` (via try/except/finally or a teardown handler).
+
+## Documentation
+
+- For docstring format (Google style) and comment language, see `rules/documentation/`.

package/dist/plugin/rules/typescript/coding-rules.md

@@ -0,0 +1,45 @@
+# TypeScript Coding Rules
+
+For language-agnostic rules, see `rules/common/coding-guidelines.md`. This document covers only TypeScript-specific rules.
+
+## Types
+
+- Assume `strict: true`. Any change that weakens tsconfig strictness needs justification in review.
+- `any` is forbidden as a rule. Receive external data as `unknown` and narrow it. If you must use `any`, comment why.
+- Give public/exported functions an explicit return type.
+- Prefer type guards and early returns over the non-null assertion (`value!`).
+- Don't silence a type error with an `as` cast — if a cast feels necessary, fix the type definition instead.
+- Consider type aliases or branded types for domain values (avoid parameter lists that are all bare `string`).
+
+## Asynchronous code
+
+- Always `await` a Promise, or mark an intentional fire-and-forget with a `void` prefix and a comment explaining why.
+- `array.forEach(async ...)` is forbidden. Use `for...of` (sequential) or `Promise.all` (parallel).
+- Don't sequentially `await` independent async operations — batch anything that can run in parallel with `Promise.all`.
+- Set a timeout on external calls via `AbortController` or client configuration.
+
+## Modules and syntax
+
+- Default to `const`; use `let` only when reassignment is required. Never use `var`.
+- Use only `===` / `!==` for equality comparisons.
+- Prefer a union type (`type Status = 'active' | 'inactive'`) or `as const` over `enum`.
+- Don't overuse barrel files (re-exporting everything through `index.ts`) — they cause circular imports and bundle bloat.
+
+## NestJS
+
+- Always receive input through a DTO with class-validator decorators. Set `whitelist: true` on the global `ValidationPipe`.
+- Explicitly attach a Guard (authentication + authorization) to protected routes. Any use of `@Public()` needs justification in review.
+- Direct access to `process.env` is forbidden. Use `ConfigService` with startup-time schema validation.
+- If you find yourself needing `forwardRef()`, treat it as a signal to revisit the design (extract a shared module, or move to an event-driven approach instead).
+- Convert exceptions via `HttpException` subclasses or an exception filter — never leak internal details into the response.
+
+## Next.js
+
+- Place `"use client"` close to the interactive leaf component that needs it — not at the top of a page or layout.
+- Treat Server Actions and Route Handlers as public endpoints: check the session, authorize, and validate the schema at the top of each one.
+- Never put secrets in `NEXT_PUBLIC_*` variables.
+- Use `next/image` for content images and `next/link` for internal navigation.
+
+## Documentation
+
+- For TSDoc format, comment language, and the OpenAPI workflow (NestJS → Next.js type generation), see `rules/documentation/`.