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

package/dist/plugin/skills/docker-patterns/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: docker-patterns
+description: A collection of Docker / Docker Compose best practices covering multi-stage builds, layer caching, image size reduction, security, healthchecks, and Compose-based dev environment setup. Reference this when creating, modifying, or reviewing a Dockerfile or docker-compose.yml.
+---
+
+# Docker Patterns
+
+A skill that captures the decision criteria for writing Dockerfiles and Docker Compose files.
+When starting from scratch, work through this order: base image selection → stage separation → cache optimization → security → healthchecks.
+
+## Multi-Stage Builds
+
+Separate the build stage from the runtime stage so that build-only tooling (compilers, devDependencies, the Composer binary, etc.) never ends up in the runtime image.
+
+Benefits:
+- The runtime image is smaller, which speeds up distribution and deployment
+- Vulnerabilities originating from build tools don't linger in the runtime environment
+- Source code and intermediate build artifacts can't leak into the final image
+
+### Node.js example
+
+```dockerfile
+# Good: use devDependencies in the build stage, hand only the build output to runtime
+FROM node:22-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+COPY --from=build /app/dist ./dist
+USER node
+CMD ["node", "dist/main.js"]
+```
+
+### Python example
+
+```dockerfile
+# Good: copy only the installed dependency output into the runtime stage
+FROM python:3.12-slim AS build
+WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
+    && rm -rf /var/lib/apt/lists/*
+COPY requirements.txt ./
+RUN pip install --prefix=/install --no-cache-dir -r requirements.txt
+
+FROM python:3.12-slim AS runtime
+WORKDIR /app
+COPY --from=build /install /usr/local
+COPY . .
+RUN useradd --create-home --shell /usr/sbin/nologin appuser
+USER appuser
+CMD ["python", "-m", "app"]
+```
+
+Keep compiler packages such as build-essential confined to the build stage. Only bring the artifacts installed via `--prefix` into the runtime stage.
+
+### PHP-FPM example
+
+```dockerfile
+# Good: resolve dependencies in a composer stage, ship only vendor/ into the runtime image
+FROM composer:2 AS vendor
+WORKDIR /app
+COPY composer.json composer.lock ./
+RUN composer install --no-dev --prefer-dist --no-scripts --no-interaction
+
+FROM php:8.3-fpm AS runtime
+WORKDIR /var/www/html
+RUN docker-php-ext-install pdo_mysql opcache
+COPY --from=vendor /app/vendor ./vendor
+COPY . .
+RUN chown -R www-data:www-data /var/www/html
+USER www-data
+CMD ["php-fpm"]
+```
+
+This keeps the (tens-of-MB) Composer binary and any dev-only dependencies excluded via `--no-dev` out of the runtime image.
+
+## Layer Caching
+
+Docker caches layers individually and re-executes every layer from the point where the copied content first changes. Dependency manifests (lock files) change far less often than source code, so copy them in on their own first, letting the dependency-install step ride the cache.
+
+```dockerfile
+# Bad: even a one-line source change forces npm ci to run every time
+COPY . .
+RUN npm ci
+
+# Good: npm ci stays cached as long as the lock file doesn't change
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+```
+
+Files to copy first, by language:
+- Node.js: package.json and package-lock.json (or pnpm-lock.yaml / yarn.lock)
+- Python: requirements.txt (or pyproject.toml plus poetry.lock / uv.lock)
+- PHP: composer.json and composer.lock
+
+Additional notes:
+- Always combine `apt-get update` and `apt-get install` into a single `RUN`. Splitting them lets a stale package-list layer get reused, causing the install to fail or pull outdated versions.
+- Place instructions that change less often earlier in the Dockerfile.
+
+## Reducing Image Size
+
+### Choosing between slim and alpine
+
+- slim (Debian-based): the default choice. glibc-compatible, so native extensions and prebuilt binaries work out of the box.
+- alpine (musl-based): reserve this for when you truly need the smallest possible size. Watch out for:
+  - Prebuilt binaries that assume glibc may not run under musl libc
+  - Python loses access to manylinux wheels, forcing a source build that's slower and often needs extras like build-base
+  - Node.js native modules (sharp, bcrypt, etc.) may also need rebuilding
+  - Subtle behavioral differences (e.g., DNS resolution) that are hard to debug
+
+When in doubt, choose slim. Reserve alpine for cases with no native dependencies, or where image size constraints are strict.
+
+### .dockerignore
+
+Keeps the build context small and prevents unwanted or sensitive files from leaking into the image. Always place one at the project root.
+
+```
+# baseline .dockerignore
+.git
+node_modules
+vendor
+__pycache__
+*.log
+.env
+.env.*
+dist
+coverage
+Dockerfile
+docker-compose*.yml
+```
+
+Without a `.dockerignore`, a Dockerfile using `COPY . .` will bake `.env` and `.git` straight into the image.
+
+## Security
+
+### Run as a non-root user
+
+Running the container process as root widens the blast radius if a vulnerability is exploited.
+
+```dockerfile
+# Bad: no USER directive (runs as root)
+CMD ["node", "server.js"]
+
+# Good: use the user bundled with the official image (node for Node.js, www-data for php-fpm)
+USER node
+CMD ["node", "server.js"]
+```
+
+For images that don't ship a ready-made user, create one with `useradd` (see the Python example above). `chown` any directories that need write access before switching `USER`.
+
+### Never bake secrets into the image
+
+Secrets passed via ARG / ENV / COPY can be recovered from `docker history` or by inspecting layers. Removing a file with `rm` in a later layer does not remove it from earlier layers.
+
+```dockerfile
+# Bad: the build-arg value persists in the image history
+ARG NPM_TOKEN
+RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc \
+    && npm ci && rm .npmrc
+
+# Good: BuildKit secret mounts never land in a layer
+RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci
+```
+
+Pass the secret at build time with something like `docker build --secret id=npmrc,src=$HOME/.npmrc .`. For runtime secrets, use environment variables (Compose's `env_file`) or a secrets-management backend, and add `.env` files to both `.dockerignore` and `.gitignore`.
+
+### Pin versions (never use `latest`)
+
+```dockerfile
+# Bad: content changes depending on when the image is pulled, breaking reproducibility
+FROM node:latest
+FROM python
+
+# Good: pin at least major.minor
+FROM node:22-slim
+FROM python:3.12-slim
+
+# Good: pin by digest when you need strict reproducibility
+FROM node:22-slim@sha256:<digest>
+```
+
+Pin versions for apt/pip packages too whenever reproducibility matters.
+
+## Healthchecks
+
+### Dockerfile HEALTHCHECK
+
+```dockerfile
+# Good: poll the app's health endpoint on a schedule
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD curl -fsS http://localhost:3000/healthz || exit 1
+```
+
+On slim-family images that lack `curl`, fall back to `wget` or a check written in the language runtime itself (e.g. `CMD ["node", "healthcheck.js"]`).
+
+### Compose healthcheck and depends_on
+
+By default, `depends_on` only guarantees *startup order*, not readiness. To wait until a database is actually ready to accept connections, combine `healthcheck` with a `condition`.
+
+```yaml
+services:
+  db:
+    image: postgres:16
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 10s
+
+  api:
+    build: .
+    depends_on:
+      db:
+        condition: service_healthy   # don't start api until db is healthy
+```
+
+Condition types:
+- `service_started`: wait only for the container to start (default)
+- `service_healthy`: wait until the healthcheck succeeds
+- `service_completed_successfully`: wait for a one-shot task (e.g. a migration) to exit successfully
+
+## Compose-Based Development Environments
+
+### Choosing between volume types
+
+- Named volumes: for persistent data you want to survive container rebuilds, such as database data
+- Bind mounts: for things like source code, where you want host-side edits reflected immediately
+
+```yaml
+services:
+  api:
+    build: .
+    volumes:
+      - .:/app                  # source via bind mount (for hot reload)
+      - /app/node_modules       # don't let the host's node_modules overwrite the container's
+  db:
+    image: postgres:16
+    volumes:
+      - db-data:/var/lib/postgresql/data   # data via named volume
+
+volumes:
+  db-data:
+```
+
+### Override files
+
+Keep the base definition in `docker-compose.yml`, and isolate dev-only differences (bind mounts, debug ports, dev commands) in `docker-compose.override.yml`. Since `docker compose up` merges the override file automatically, production and CI should explicitly pass `-f docker-compose.yml` only, excluding the dev-only overrides.
+
+### Bind ports to localhost
+
+```yaml
+    # Bad: exposed on all interfaces, reachable from the LAN or beyond
+    ports:
+      - "5432:5432"
+
+    # Good: bind a dev database to the loopback interface only
+    ports:
+      - "127.0.0.1:5432:5432"
+```
+
+For services the host never needs to reach directly, skip `ports` entirely and rely on container-to-container communication (via service-name resolution).
+
+### Network isolation
+
+Minimize the reachable surface. Put only the reverse proxy on the outward-facing network, and keep the database reachable solely from the app.
+
+```yaml
+services:
+  proxy:
+    networks: [frontend]
+  api:
+    networks: [frontend, backend]
+  db:
+    networks: [backend]    # unreachable from proxy
+
+networks:
+  frontend:
+  backend:
+```
+
+## Anti-Patterns
+
+- Specifying a base image as `FROM xxx:latest` (breaks reproducibility)
+- Writing `COPY . .` before the dependency-install step (invalidates the cache on every build)
+- Running `COPY . .` without a `.dockerignore` (leaks `.git` or `.env` into the image)
+- Passing secrets via ARG / ENV (recoverable from `docker history`)
+- Running the app as root because `USER` was never set
+- Splitting `apt-get update` and `apt-get install` into separate `RUN` instructions
+- Leaving the apt cache (`/var/lib/apt/lists`) or pip cache in the image instead of clearing it
+- Cramming multiple processes into one container (app + cron + nginx, etc.)
+- Assuming `depends_on` alone guarantees the database is ready (no `condition` specified)
+- Exposing a dev database port on `0.0.0.0`
+- Reaching for alpine without considering native extension compatibility
+- Writing logs to a file instead of stdout/stderr (let the runtime handle log collection)
+- Running `git clone` inside the image instead of `COPY`-ing through the build context
+
+## Related
+
+- Use `/code-review` when reviewing Dockerfile / Compose file changes

package/dist/plugin/skills/docs-site/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: docs-site
+description: A pattern library for building and operating a documentation site with Docusaurus. Covers i18n (ja/en) structure, automatic OpenAPI generation from NestJS, wiring OpenAPI/TypeDoc output into Docusaurus, type and client generation with openapi-typescript / orval, templates for hand-written reference pages, and CI freshness checks. Use this when setting up a new documentation site, adding pages, updating API references, syncing translations, or building a type-generation pipeline.
+---
+
+# docs-site: Docusaurus documentation site patterns
+
+This skill is a pattern library focused on "how to build it." The authoritative source for the conventions themselves lives in `rules/documentation/` (aimed at repository maintainers); this skill assumes those conventions are already settled and provides the implementation steps.
+
+## Baseline conventions assumed here
+
+- Locales are `ja` (default) + `en`. Hand-written guides must exist in both languages. Auto-generated reference pages exist only in the default locale.
+- NestJS APIs are documented by auto-generating from OpenAPI (hand-transcribing is not allowed). For TS libraries, prefer TypeDoc auto-generation. Python / PHP are handled with hand-written templates plus a consistency check.
+- Hand-written reference pages must include a `source: src/path/file.ts#functionName` key in the frontmatter.
+- Links to tests use a repository-absolute URL anchored to the default branch (never pin to a commit SHA).
+
+## 1. Basic Docusaurus i18n setup
+
+### docusaurus.config.js
+
+```js
+// docusaurus.config.js (excerpt)
+module.exports = {
+  title: 'Docs',
+  url: 'https://docs.example.com',
+  baseUrl: '/',
+  i18n: {
+    defaultLocale: 'ja',          // default locale is ja
+    locales: ['ja', 'en'],
+  },
+  themeConfig: {
+    navbar: {
+      // always include a locale-switcher dropdown
+      items: [{ type: 'localeDropdown', position: 'right' }],
+    },
+  },
+};
+```
+
+### Directory structure
+
+The source-of-truth content for the default locale (ja) lives under `docs/`, and the en translation mirrors the same structure under `i18n/en/`.
+
+```text
+docs/
+  guides/getting-started.md        # ja original (source of truth)
+i18n/
+  en/
+    docusaurus-plugin-content-docs/
+      current/
+        guides/getting-started.md  # en translation (same relative path as docs/)
+    code.json                      # translations for UI strings
+```
+
+### Translation workflow
+
+```bash
+# 1. Generate translation files for UI strings / sidebar labels (for en)
+npm run write-translations -- --locale en
+
+# 2. Place the en translation of a hand-written guide under i18n/en/.../current/
+#    at the same relative path, then translate it
+cp docs/guides/getting-started.md \
+   i18n/en/docusaurus-plugin-content-docs/current/guides/getting-started.md
+
+# 3. Run the dev server per locale to check it (dev server serves one locale at a time)
+npm run start -- --locale en
+
+# 4. A production build verifies all locales together
+npm run build
+```
+
+Whenever the original (ja) content is updated, update the en translation in the same PR. Auto-generated reference pages (from OpenAPI / TypeDoc) exist only in the default locale — do not copy them into `i18n/en/`.
+
+## 2. Generating OpenAPI output from NestJS
+
+Prepare a generation-only script that doesn't depend on the server actually listening. It's important that this can run in CI without opening a port.
+
+```ts
+// scripts/generate-openapi.ts
+import { NestFactory } from '@nestjs/core';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { writeFileSync } from 'fs';
+import { AppModule } from '../src/app.module';
+
+async function generate() {
+  // Build only the application context, without calling listen()
+  const app = await NestFactory.create(AppModule, { logger: false });
+
+  const config = new DocumentBuilder()
+    .setTitle('API').setVersion('1.0.0').addBearerAuth()
+    .build();
+
+  const document = SwaggerModule.createDocument(app, config);
+  writeFileSync('openapi.json', JSON.stringify(document, null, 2));
+
+  await app.close();
+}
+
+generate();
+```
+
+```jsonc
+// package.json (excerpt)
+{ "scripts": { "openapi:generate": "ts-node scripts/generate-openapi.ts" } }
+```
+
+Enabling the `@nestjs/swagger` CLI plugin lets it auto-infer `@ApiProperty` from DTO properties, which reduces missing-decorator mistakes.
+
+```jsonc
+// nest-cli.json
+{
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "plugins": [
+      { "name": "@nestjs/swagger", "options": { "introspectComments": true } }
+    ]
+  }
+}
+```
+
+## 3. Pulling OpenAPI into Docusaurus
+
+Use `docusaurus-plugin-openapi-docs` to generate MDX pages from `openapi.json`.
+
+```js
+// docusaurus.config.js (excerpt)
+module.exports = {
+  plugins: [
+    [
+      'docusaurus-plugin-openapi-docs',
+      {
+        id: 'api',
+        docsPluginId: 'classic',
+        config: {
+          myApi: {
+            specPath: 'openapi.json',          // the generated spec
+            outputDir: 'docs/api',             // output location (default locale only)
+            sidebarOptions: {
+              groupPathsBy: 'tag',             // group by tag
+              categoryLinkSource: 'tag',
+            },
+          },
+        },
+      },
+    ],
+  ],
+  themes: ['docusaurus-theme-openapi-docs'],
+};
+```
+
+```js
+// sidebars.js (excerpt): pull in the generated sidebar
+module.exports = {
+  docs: [
+    { type: 'category', label: 'Guides', items: [{ type: 'autogenerated', dirName: 'guides' }] },
+    { type: 'category', label: 'API Reference', items: require('./docs/api/sidebar.js') },
+  ],
+};
+```
+
+```bash
+# Regenerate (run this every time the API changes; clear old pages before rebuilding)
+npm run openapi:generate                      # in the API repository
+npx docusaurus clean-api-docs myApi           # remove existing generated output
+npx docusaurus gen-api-docs myApi             # regenerate
+```
+
+The generated `docs/api/` content is served only in the default locale (the ja site) — do not create a translated copy under `i18n/en/`, and do not hand-edit it.
+
+## 4. Generating Next.js types and clients from OpenAPI
+
+Use `openapi-typescript` if you only need types, or `orval` if you also want a fetch client. In both cases, standardize the output location as `src/generated/`.
+
+```jsonc
+// package.json (excerpt): generate types only
+{ "scripts": { "codegen:types": "openapi-typescript ../api/openapi.json -o src/generated/api-types.ts" } }
+```
+
+```ts
+// orval.config.ts: generate both types and client
+import { defineConfig } from 'orval';
+
+export default defineConfig({
+  myApi: {
+    input: '../api/openapi.json',
+    output: {
+      target: 'src/generated/api-client.ts',
+      client: 'fetch',               // use 'react-query' if you're using React Query
+      clean: true,                   // remove stale files on regeneration
+    },
+  },
+});
+```
+
+Enforce the "no hand-editing" rule with a two-pronged approach: exclude generated files from lint, and detect regeneration drift in CI (see section 7).
+
+```jsonc
+// .eslintrc.json (excerpt): don't lint generated output — this signals it isn't meant to be hand-edited
+{
+  "ignorePatterns": ["src/generated/**"]
+}
+```
+
+`src/generated/` should still be committed (so reviewers can see the diff), but a PR containing manual edits to it will fail the CI freshness check.
+
+## 5. Pulling TypeDoc into Docusaurus
+
+```js
+// docusaurus.config.js (excerpt)
+module.exports = {
+  plugins: [
+    [
+      'docusaurus-plugin-typedoc',
+      {
+        entryPoints: ['../packages/sdk/src/index.ts'],
+        tsconfig: '../packages/sdk/tsconfig.json',
+        out: 'docs/sdk',              // output location (default locale only)
+        sidebar: { autoConfiguration: true },
+      },
+    ],
+  ],
+};
+```
+
+```js
+// sidebars.js (excerpt): pull in the sidebar generated by TypeDoc
+module.exports = {
+  docs: [
+    { type: 'category', label: 'SDK Reference', items: require('./docs/sdk/typedoc-sidebar.cjs') },
+  ],
+};
+```
+
+Embed links to tests via `@see` in TSDoc comments. Links should use an absolute URL anchored to the default branch (never pin to a SHA).
+
+```ts
+/**
+ * Calculates the order total including tax.
+ * @param items - array of order line items
+ * @see {@link https://github.com/example-org/sdk/blob/main/test/order.spec.ts | order.spec.ts test cases}
+ */
+export function calcOrderTotal(items: OrderItem[]): number { /* ... */ }
+```
+
+## 6. Full template for a hand-written function reference
+
+For languages such as Python / PHP where auto-generation isn't available. The `source` frontmatter key is required so the consistency check (`/update-docs`) can trace back to the implementation.
+
+```markdown
+---
+id: calc-order-total
+title: calc_order_total
+source: src/services/order.py#calc_order_total
+---
+
+## Overview
+
+Calculates the tax-inclusive total from an array of order line items.
+
+## Signature
+
+\`\`\`python
+def calc_order_total(items: list[OrderItem], tax_rate: Decimal = Decimal("0.10")) -> int
+\`\`\`
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| items | list[OrderItem] | Yes | Array of order line items. An empty array is allowed |
+| tax_rate | Decimal | No | Tax rate. Defaults to 0.10 |
+
+## Output
+
+The tax-inclusive total (in yen, as an int). Returns 0 for an empty array.
+
+## Errors
+
+| Exception | Code | Condition |
+| --- | --- | --- |
+| ValueError | E_NEGATIVE_PRICE | A line item has a negative unit price |
+| ValueError | E_INVALID_TAX_RATE | tax_rate is less than 0 or greater than or equal to 1 |
+
+## Example
+
+\`\`\`python
+total = calc_order_total(items, tax_rate=Decimal("0.10"))  # => 1100
+\`\`\`
+
+## Tests
+
+- [tests/services/test_order.py](https://github.com/example-org/shop-api/blob/main/tests/services/test_order.py)
+```
+
+As with hand-written guides, this kind of reference page should also be prepared in both ja and en. When the implementation changes, use the `source` key as the anchor for finding and updating the corresponding page.
+
+## 7. Example CI freshness check implementation
+
+The principle is: "regenerate it, and fail if there's a diff." Apply this to both `openapi.json` and the generated client.
+
+```yaml
+# .github/workflows/docs-freshness.yml
+name: docs-freshness
+on: [pull_request]
+
+jobs:
+  freshness:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      # Regenerate openapi.json and check it matches what's committed
+      - run: npm run openapi:generate
+      - run: git diff --exit-code openapi.json
+      # Regenerate the client/types and check src/generated/ has no diff
+      - run: npm run codegen:types && npx orval
+      - run: git diff --exit-code src/generated/
+```
+
+The same idea applies in GitLab CI — just line up "regenerate → `git diff --exit-code`" as script steps in the job.
+
+This check catches both failure modes: (a) a PR that changed the API but forgot to update `openapi.json`, and (b) a PR that hand-edited generated output.
+
+## 8. Anti-patterns
+
+| Anti-pattern | Problem | Do this instead |
+| --- | --- | --- |
+| Hand-writing API response types | Falls out of sync with API changes; types and reality drift apart | Generate into `src/generated/` with openapi-typescript / orval |
+| Hand-editing generated output (`docs/api`, `src/generated/`) | Gets wiped out on the next regeneration, and fails the CI freshness check anyway | Edit the source of truth (decorators, TSDoc, the spec) and regenerate |
+| Test links pinned to a commit SHA | Keeps pointing at old code and drifts from the current state | Use an absolute URL anchored to the default branch |
+| Leaving translations behind (only updating the ja original) | English readers keep seeing stale information | Update ja and en together in the same PR for hand-written guides |
+| Orphan pages missing from the sidebar | Unreachable except via search; nobody knows they exist | Always register pages in sidebars.js (either autogenerated or explicit) |
+
+## Related
+
+- Source of truth for conventions: `rules/documentation/` (for repository maintainers)
+- API design guidance itself: the api-design skill
+- Running the implementation/documentation consistency check: `/update-docs`