@vpnsin/devkit 0.1.3

package/templates/README.template.md

@@ -0,0 +1,51 @@
+# Project Name
+
+> One-line description of what this project does.
+
+## Features
+
+- …
+- …
+
+## Getting started
+
+### Prerequisites
+
+- Node.js >= 18.18
+- npm
+
+### Install
+
+```bash
+npm install
+```
+
+### Develop
+
+```bash
+npm run dev
+```
+
+## Scripts
+
+| Script               | Description                  |
+| -------------------- | ---------------------------- |
+| `npm run lint`       | Lint with ESLint             |
+| `npm run format`     | Format with Prettier         |
+| `npm run type-check` | Type-check with `tsc`        |
+| `npm run lint:md`    | Lint Markdown                |
+| `npm run build`      | Production build (if present)|
+
+## Contributing
+
+See [CONTRIBUTING](.github/CONTRIBUTING.md). Commits follow
+[Conventional Commits](https://www.conventionalcommits.org/); releases are
+automated with release-please.
+
+## Security
+
+See [SECURITY](.github/SECURITY.md) for how to report vulnerabilities.
+
+## License
+
+<!-- e.g. MIT © Year Author -->

package/templates/app/backend/Dockerfile

@@ -0,0 +1,24 @@
+# syntax=docker/dockerfile:1
+
+# ---- build ----
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# ---- runtime ----
+FROM node:22-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY --from=build /app/dist ./dist
+EXPOSE 3000
+USER node
+
+# Probe the /health route using Node's built-in fetch (no curl/wget needed).
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 CMD node -e "fetch('http://localhost:'+(process.env.PORT||3000)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["node", "dist/server.js"]

package/templates/app/backend/dockerignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.git
+.github
+.env
+*.log
+npm-debug.log*

package/templates/app/backend/env.example

@@ -0,0 +1,2 @@
+NODE_ENV=development
+PORT=3000

package/templates/app/backend/src/app.ts

@@ -0,0 +1,22 @@
+import express, { type Express } from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import { healthRouter } from './routes/health.js';
+
+// App factory — keep it pure (no listen()) so tests can import and exercise it.
+export function createApp(): Express {
+  const app = express();
+
+  app.use(helmet());
+  app.use(cors());
+  app.use(express.json());
+
+  app.use('/health', healthRouter);
+
+  // Fallback 404.
+  app.use((_req, res) => {
+    res.status(404).json({ error: 'Not found' });
+  });
+
+  return app;
+}

package/templates/app/backend/src/env.ts

@@ -0,0 +1,8 @@
+import 'dotenv/config';
+
+// Central, typed access to environment config. Extend with validation
+// (e.g. zod) as the surface grows.
+export const env = {
+  NODE_ENV: process.env.NODE_ENV ?? 'development',
+  PORT: Number(process.env.PORT ?? 3000),
+} as const;

package/templates/app/backend/src/routes/health.ts

@@ -0,0 +1,7 @@
+import { Router } from 'express';
+
+export const healthRouter = Router();
+
+healthRouter.get('/', (_req, res) => {
+  res.json({ status: 'ok', uptime: process.uptime() });
+});

package/templates/app/backend/src/server.ts

@@ -0,0 +1,19 @@
+import { createApp } from './app.js';
+import { env } from './env.js';
+
+const app = createApp();
+
+const server = app.listen(env.PORT, () => {
+  // eslint-disable-next-line no-console
+  console.log(`API listening on http://localhost:${env.PORT} (${env.NODE_ENV})`);
+});
+
+// Graceful shutdown so in-flight requests drain before the process exits.
+function shutdown(signal: string): void {
+  // eslint-disable-next-line no-console
+  console.log(`${signal} received, shutting down…`);
+  server.close(() => process.exit(0));
+}
+
+process.on('SIGINT', () => shutdown('SIGINT'));
+process.on('SIGTERM', () => shutdown('SIGTERM'));

package/templates/app/frontend/app/globals.css

@@ -0,0 +1,28 @@
+:root {
+  color-scheme: light dark;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+  font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
+  line-height: 1.5;
+}
+
+main {
+  max-width: 48rem;
+  margin: 0 auto;
+  padding: 4rem 1.5rem;
+}
+
+code {
+  font-family: ui-monospace, 'SFMono-Regular', Menlo, monospace;
+  background: rgba(127, 127, 127, 0.15);
+  padding: 0.1rem 0.35rem;
+  border-radius: 0.25rem;
+}

package/templates/app/frontend/app/layout.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from 'next';
+import type { ReactNode } from 'react';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: 'App',
+  description: 'Bootstrapped with devkit',
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/app/frontend/app/page.tsx

@@ -0,0 +1,10 @@
+export default function Home() {
+  return (
+    <main>
+      <h1>It works 🎉</h1>
+      <p>
+        Edit <code>app/page.tsx</code> and save to reload.
+      </p>
+    </main>
+  );
+}

package/templates/app/frontend/env.example

@@ -0,0 +1,5 @@
+# Server-only secrets go here (never exposed to the browser).
+# API_BASE_URL=http://localhost:3000
+
+# Public vars MUST be prefixed with NEXT_PUBLIC_ to reach the client.
+NEXT_PUBLIC_APP_NAME=My App

package/templates/app/frontend/next.config.mjs

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+};
+
+export default nextConfig;

package/templates/claude/skills/design-craft/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: design-craft
+description: >-
+  Elevate the user experience and visual design of the site. Use when polishing
+  UI, redesigning a page or section, adding motion/micro-interactions, tightening
+  typography/spacing/color, or auditing design quality. Runs three activity sets —
+  Define (taste & design language), Design (layout/type/color/space), Polish
+  (motion & micro-interactions) — then a Review gate. Works on Next.js + Tailwind
+  sites. Synthesises three skills: emilkowalski/skill, pbakaus/impeccable, and
+  Leonxlnx/taste-skill.
+---
+
+# Design Craft
+
+A three-phase protocol for making interfaces that feel **considered, premium, and
+alive** — not generic AI "slop". It unifies three sources:
+
+- **emilkowalski/skill** (`emil-design-eng`) — motion, micro-interaction, and the
+  invisible details that compound. _"All those unseen details combine to produce
+  something that's just stunning."_
+- **pbakaus/impeccable** — design quality, consistency, and a concrete anti-pattern
+  catalogue. Plan (shape) before you build.
+- **Leonxlnx/taste-skill** — anti-slop framework: infer the brief, tune taste dials,
+  map a coherent design system before coding.
+
+**Taste is trained, not innate.** Study great work, reverse-engineer why it feels
+right, and apply the concrete rules below rather than defaulting to the obvious.
+
+## How to use this skill
+
+- **Full redesign of a page/section** → run Activity Sets 1 → 2 → 3, then Review.
+- **Visual tweak** (spacing/type/color) → Activity Set 2 + Review.
+- **Add/refine motion** → Activity Set 3 + Review.
+- **"Make this feel better" / audit** → Review gate first to find issues, then the
+  relevant set to fix them.
+
+Always **read the component and match the surrounding conventions** before editing,
+and always finish with the Review gate. On these sites: Tailwind utilities + theme
+tokens, `next/image`, mobile-first; verify at the dev server and keep
+`type-check` / `lint` / `build` green.
+
+---
+
+## Activity Set 1 — Define (taste & design language)
+
+_Establish intent before touching code (impeccable: context-first; taste: infer the brief)._
+
+1. **State the context** in one or two lines: audience, brand-vs-product, voice,
+   the single feeling the page should evoke. If the repo has a `DESIGN.md` /
+   `CLAUDE.md`, read it; otherwise infer from the existing site and say what you
+   inferred.
+2. **Tune three dials (1–10) and write them down** so choices are deliberate:
+   - **DESIGN_VARIANCE** — layout experimentation (low = centred/clean; high = asymmetric/editorial).
+   - **MOTION_INTENSITY** — animation depth (low = hover/press only; high = scroll-driven/magnetic).
+   - **VISUAL_DENSITY** — information per viewport (low = spacious; high = dense dashboard).
+   - _Premium eco / marketing brand (e.g. Flora Dine) default:_ variance **4**, motion **4**, density **3** — calm, trustworthy, spacious.
+3. **Map the design system** so everything is reused, not reinvented: type scale,
+   spacing rhythm (8px grid), colour tokens (already in the Tailwind theme),
+   radius, shadow, and the existing component inventory. New work must pull from
+   these tokens — no hard-coded hex or one-off spacing.
+
+**Deliverable:** a 3–5 line direction (context + dials + the tokens you'll use).
+
+---
+
+## Activity Set 2 — Design (layout, type, colour, space)
+
+_Shape the composition, then build it (impeccable + taste). Avoid generic patterns._
+
+**Shape first.** Describe the layout and visual hierarchy in words before writing
+JSX — what leads, what supports, where the eye goes.
+
+**Typography**
+
+- Clear scale with real hierarchy (don't size everything the same).
+- Body line-height ≥ 1.5; tighten display headings.
+- Avoid the obvious defaults for display type (Arial, system stack, and plain
+  **Inter** as the "AI default"). The brand font should do the talking.
+
+**Colour**
+
+- **Never pure black or pure gray** — always tint toward the brand (e.g. text is a
+  very dark brand-tinted neutral, not `#000`).
+- **No gray text on coloured backgrounds** — it reads muddy; use a tint of the
+  background or an on-colour token.
+- Maintain **4.5:1** contrast for text. Drive everything from theme tokens.
+
+**Spacing & layout**
+
+- 8px rhythm; treat white space as a design element, not leftover.
+- Use the dials: raise variance with an asymmetric hero or offset grid when the
+  brand allows; keep density low for a premium feel.
+
+**Avoid the "slop" tells** (taste + impeccable anti-patterns)
+
+- Purple→blue "AI gradient"; bouncy/elastic easing; everything wrapped in cards;
+  **cards nested inside cards**; side-tab coloured borders; skipped heading levels;
+  undersized touch targets; centered-everything with no hierarchy.
+- In UI microcopy, vary punctuation — don't lean on the em-dash as a verbal tic
+  (a common AI tell). Keep copy specific and human.
+
+**Deliverable:** the built/edited section using tokens, with hierarchy that reads
+at a glance and none of the anti-patterns above.
+
+---
+
+## Activity Set 3 — Polish (motion & micro-interactions)
+
+_The emil-design-eng layer — where "fine" becomes "loved". This is the most concrete set._
+
+### Decide whether to animate at all
+
+| Frequency | Decision |
+| --- | --- |
+| 100+×/day (keyboard, command palette) | **Never animate** |
+| Tens×/day (hover, list nav) | Remove or drastically reduce |
+| Occasional (modals, drawers, toasts) | Standard animation |
+| Rare / first-time (onboarding, celebration) | Can add delight |
+
+Every animation must answer **"why does this animate?"** — spatial consistency,
+state indication, feedback, or preventing a jarring change. "Looks cool" + seen
+often = don't.
+
+### Easing — use custom curves, never `ease-in` on UI
+
+```css
+--ease-out:    cubic-bezier(0.23, 1, 0.32, 1);   /* enter/exit */
+--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);  /* move/morph on screen */
+--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);   /* drawers/sheets */
+```
+
+- Entering/exiting → `ease-out`. Moving/morphing → `ease-in-out`. Hover/colour →
+  `ease`. Constant motion → `linear`.
+- **Never `ease-in`** on UI (delays the first frame users watch most). Built-in CSS
+  easings are too weak — use the curves above.
+
+### Duration — keep UI under 300ms
+
+| Element | Duration |
+| --- | --- |
+| Button press feedback | 100–160ms |
+| Tooltip / small popover | 125–200ms |
+| Dropdown / select | 150–250ms |
+| Modal / drawer | 200–500ms |
+
+### Core rules
+
+- **Animate only `transform` and `opacity`** (GPU; skips layout/paint). Never
+  animate `width`/`height`/`margin`/`padding`/`top`/`left`.
+- **Press feedback:** `:active { transform: scale(0.97) }` on pressable elements
+  (subtle, 0.95–0.98).
+- **Never enter from `scale(0)`** — start `scale(0.95)` + `opacity: 0` (nothing in
+  reality appears from nothing).
+- **Origin-aware popovers** scale from their trigger (`transform-origin`), not
+  center. **Modals stay centered.**
+- **Asymmetric timing:** slow where the user is deciding (e.g. hold-to-delete 2s
+  linear), snappy where the system responds (200ms ease-out). Make exits a touch
+  faster than enters.
+- **Stagger** list entries 30–80ms; never block interaction during a stagger.
+- **Springs** for drag/gesture & "alive" elements (they keep velocity when
+  interrupted): Apple-style `{ type: 'spring', duration: 0.5, bounce: 0.2 }`; keep
+  bounce 0.1–0.3.
+- Prefer **CSS transitions** over keyframes for interruptible UI; use `@starting-style`
+  for enter animations; reach for `clip-path` for reveals/wipes/comparison sliders.
+- **Tailwind note:** these sites have `tailwindcss-animate`; for bespoke motion add a
+  token-based transition (`transition-transform duration-200 ease-[cubic-bezier(...)]`)
+  rather than `transition-all`.
+
+### Accessibility (non-negotiable)
+
+- `@media (prefers-reduced-motion: reduce)` → keep opacity/colour, drop movement
+  (reduce, don't remove).
+- Gate hover effects behind `@media (hover: hover) and (pointer: fine)` so touch
+  taps don't trigger them.
+
+---
+
+## Review gate (run before shipping)
+
+Combine all three skills' checks. Produce findings as a **Before → After → Why**
+markdown table (emil's required format), not prose bullets.
+
+**Technical audit** (impeccable `audit`)
+
+- A11y: 4.5:1 contrast, keyboard reachable + visible focus, real `<label>`s,
+  44×44px targets, `prefers-reduced-motion` respected.
+- Performance: only `transform`/`opacity` animated; no `transition: all`; images via
+  `next/image` with correct `sizes`.
+- Responsive: no horizontal overflow and correct reflow at 480 / 768 / 1024 / 1440.
+
+**Creative critique** (impeccable `critique` + taste pre-flight)
+
+- Hierarchy reads at a glance; one clear focal point per view.
+- Clarity of copy and CTAs; emotional resonance matches the brand feeling.
+- **Cohesion:** easing, duration, and vibe are unified — motion matches mood
+  (playful can bounce; a premium brand stays crisp/calm).
+- No "slop" tells from Activity Set 2 remain.
+
+**Emil's code checklist** (fix on sight)
+
+| Issue | Fix |
+| --- | --- |
+| `transition: all` | name the property: `transition: transform 200ms var(--ease-out)` |
+| `scale(0)` entry | `scale(0.95)` + `opacity: 0` |
+| `ease-in` on UI | `ease-out` / custom curve |
+| `transform-origin: center` on popover | set to trigger (modals exempt) |
+| Animation on a keyboard action | remove |
+| Duration > 300ms on UI | reduce to 150–250ms |
+| Hover without `@media (hover)` | add the media query |
+| Same enter/exit speed | make the exit faster |
+| Everything appears at once | add 30–80ms stagger |
+
+**Then verify the build:** `npm run type-check`, `npm run lint`, `npm run build`,
+and look at it on the dev server (responsive widths above).
+
+---
+
+## Set your project's defaults
+
+Record the design direction once — in `CLAUDE.md` or a `DESIGN.md` — so every run
+is consistent: the brand's one-line feeling, the three dial values, and the token
+set to reuse. Then Activity Set 1 reads it instead of re-inferring each time.
+
+> Example (premium / calm brand): dials variance **4** / motion **4** / density
+> **3**; `ease-out` motion under ~250ms; lean on the existing theme tokens and the
+> 8px grid.

package/templates/cspell.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
+  "version": "0.2",
+  "language": "en",
+  "words": [
+    "commitlint",
+    "devkit",
+    "dotenv",
+    "esbenp",
+    "lintstagedrc",
+    "markdownlint",
+    "npmrc",
+    "nvmrc",
+    "tsup",
+    "unconfigured",
+    "vitest"
+  ],
+  "ignorePaths": [
+    "node_modules/**",
+    "dist/**",
+    "build/**",
+    "coverage/**",
+    ".next/**",
+    "*.log",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "CHANGELOG.md"
+  ]
+}

package/templates/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  # npm dependencies
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      # Batch low-risk updates into a single PR to cut noise.
+      minor-and-patch:
+        update-types: [minor, patch]
+
+  # GitHub Actions used in workflows
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

package/templates/editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{bat,cmd}]
+end_of_line = crlf

package/templates/github/CODEOWNERS

@@ -0,0 +1,12 @@
+# Code owners are automatically requested for review on matching paths.
+# Docs: https://docs.github.com/articles/about-code-owners
+#
+# Replace @OWNER with your username or team (e.g. @your-org/maintainers).
+
+# Default owner for everything in the repo
+* @OWNER
+
+# Examples — uncomment and adjust:
+# /.github/        @your-org/devops
+# /src/api/        @your-org/backend
+# *.md             @your-org/docs

package/templates/github/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+Thanks for contributing! This repository uses shared tooling from
+[`devkit`](https://github.com/vpnsin/devkit) — ESLint, Prettier,
+commitlint, markdownlint, Husky, and CI/release workflows.
+
+## Getting started
+
+- **Node.js** >= 18.18 and **npm**
+- `npm install` (sets up Git hooks via Husky automatically)
+
+## Development workflow
+
+1. Branch off `main` (or `dev`):
+   `git checkout -b feat/short-description`
+2. Make your changes. On commit, the pre-commit hook auto-formats and lints
+   staged files.
+3. Before pushing, verify locally:
+
+   ```bash
+   npm run type-check
+   npm run lint
+   npm run lint:md
+   npm run format:check
+   npm run build   # if the repo has a build step
+   ```
+
+## Commit messages — Conventional Commits (required)
+
+The `commit-msg` hook enforces them, and release-please uses them to compute the
+version bump and changelog.
+
+| Type                                                                 | Effect        |
+| -------------------------------------------------------------------- | ------------- |
+| `feat:`                                                              | minor release |
+| `fix:`                                                               | patch release |
+| `docs:` `chore:` `refactor:` `test:` `ci:` `build:` `perf:` `style:` | no release    |
+| `feat!:` / `BREAKING CHANGE:` footer                                 | major release |
+
+Example: `feat(auth): add password reset flow`
+
+## Pull requests
+
+- Keep PRs focused and fill in the PR template.
+- Make sure CI is green.
+- A code owner (see `CODEOWNERS`) will review and merge.
+
+## Releases
+
+Merging to `main` opens or updates a **release-please** PR. Merging that PR
+publishes the GitHub release, tag, and changelog.

package/templates/github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,34 @@
+name: Bug report
+description: Report a problem so we can fix it
+labels: [bug]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Go to '...'
+        2. Run '...'
+        3. See error
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version / environment
+      description: Package version, Node version, OS.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / screenshots
+      description: Relevant output (will be rendered as code).
+      render: shell

package/templates/github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/vpnsin/devkit/security/advisories/new
+    about: Please report security issues privately, not as public issues.

package/templates/github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this solve? What's the use case?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you've thought about.

package/templates/github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+<!-- PR title MUST be a Conventional Commit, e.g. "feat: add X" or "fix: handle Y"
+     — release-please reads it to compute the version bump and changelog. -->
+
+## Summary
+
+<!-- What does this PR change, and why? Link any issue: Closes #123 -->
+
+## Type of change
+
+- [ ] `feat` — new feature (minor bump)
+- [ ] `fix` — bug fix (patch bump)
+- [ ] `refactor` — no behaviour change
+- [ ] `docs` — documentation only
+- [ ] `chore` / `ci` / `build` — tooling, deps, config
+- [ ] `perf` / `style` / `test`
+
+## Checklist
+
+- [ ] PR title is a Conventional Commit (`feat:`, `fix:`, `chore:` …)
+- [ ] `npm run type-check` passes
+- [ ] `npm run lint` passes (+ `npm run lint:md` if docs changed)
+- [ ] `npm run build` succeeds (if applicable)
+- [ ] No secrets committed (env values stay in the deploy platform / local `.env`)
+
+## Screenshots / notes
+
+<!-- Before/after for UI changes; migration notes; follow-ups -->