@ifi/oh-pi-skills 0.2.8 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifi/oh-pi-skills",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "On-demand skill packs for pi: web-search, debug-helper, git-workflow, and more.",
   "keywords": [
     "pi-package"

package/skills/flutter-serverpod-mvp/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: flutter-serverpod-mvp
+description:
+  Scaffold and evolve full-stack Flutter + Serverpod MVPs using devenv, Riverpod + Hooks,
+  strict i18n, and GoRouter shell routing patterns inspired by OpenBudget.
+---
+
+# Flutter + Serverpod MVP (OpenBudget-style)
+
+Use this skill when the user wants to:
+
+- start a **new full-stack Flutter + Serverpod project**,
+- add a major feature to an existing Flutter + Serverpod monorepo,
+- enforce OpenBudget-style rules for **devenv**, **Riverpod + Hooks**, **i18n**, and **routing**.
+
+## Core Standards (non-negotiable)
+
+These conventions are extracted from the OpenBudget setup and should be applied by default.
+
+1. **Workspace-first monorepo**
+   - Keep app/server/shared modules in one workspace.
+   - Use `melos` scripts from the workspace root.
+
+2. **Hooks + Riverpod architecture**
+   - Use `HookConsumerWidget` for widgets that read providers.
+   - Use `HookWidget` for widgets without provider reads.
+   - Prefer custom hooks (`use*`) over ad-hoc widget state.
+   - Use `@riverpod`/`riverpod_annotation` providers, not manual legacy provider styles.
+
+3. **Serverpod full-stack flow**
+   - Keep API/domain logic in `server/` with endpoint + service pattern.
+   - Generate protocol/client code whenever models/endpoints change.
+   - App calls Serverpod via a dedicated `serverpodClientProvider`.
+
+4. **Strict i18n discipline**
+   - No hardcoded user-facing strings in UI.
+   - Use ARB + generated `AppLocalizations` API.
+   - Add and run a hardcoded text checker (OpenBudget-style `tools/check_localized_ui_text.dart`).
+
+5. **Structured GoRouter routing**
+   - Route constants in `route_names.dart`.
+   - Router provider in `app_router.dart` via `@riverpod`.
+   - Auth redirect in a pure/testable helper function.
+   - Use `StatefulShellRoute.indexedStack` for bottom-tab apps with separate navigator stacks.
+
+6. **devenv as the operational entrypoint**
+   - Local infra (Postgres/Redis) + scripts + process logs under devenv.
+   - `devenv up` should bring up backend dependencies and server.
+
+## Recommended Project Layout
+
+```text
+<project>/
+├── app/                    # Flutter app
+├── server/                 # Serverpod backend
+├── client/                 # Generated serverpod protocol client
+├── core/                   # Shared Dart models/utilities (no Flutter)
+├── ui/                     # Shared Flutter UI package
+├── lints/                  # Centralized analyzer/lint config (optional but recommended)
+├── test_utils/             # Shared test helpers
+├── tools/                  # Scripts (e.g. l10n hardcoded text check)
+├── pubspec.yaml            # Workspace root + melos config
+├── devenv.nix              # Development environment and scripts
+├── devenv.yaml             # devenv inputs
+└── .github/workflows/ci.yml
+```
+
+## Bootstrap Workflow for a New MVP
+
+When asked to create a new project, execute this order:
+
+1. **Collect project inputs**
+   - Project name, organization ID, app bundle IDs, default flavor, API hostnames.
+
+2. **Scaffold workspace root**
+   - Root `pubspec.yaml` with Dart workspace members.
+   - `melos` scripts for analyze/test/generate/serverpod generation.
+
+3. **Scaffold Serverpod package**
+   - `server/pubspec.yaml` with `serverpod` dependencies.
+   - `server/config/{development,test,production}.yaml`.
+   - `server/config/generator.yaml` pointing to `../client`.
+   - Initial endpoint/service files.
+
+4. **Scaffold Flutter app package**
+   - Dependencies: `hooks_riverpod`, `flutter_hooks`, `go_router`,
+     `riverpod_annotation`, `serverpod_flutter`, auth package, localization deps.
+   - `l10n.yaml` configured with generated output directory.
+   - app bootstrap with `MaterialApp.router`, localization delegates, and router provider.
+
+5. **Wire full-stack client access**
+   - Add `serverpodClientProvider` with environment override support.
+   - Ensure test runtime handling for connectivity monitor.
+
+6. **Add i18n and routing foundations**
+   - `lib/l10n/app_en.arb` + generated localization output path.
+   - `route_names.dart` for all route/path constants.
+   - `app_router.dart` with auth redirects + shell routing where needed.
+
+7. **Add devenv and CI**
+   - `devenv.nix` with scripts for lint/test/generate/server start.
+   - `devenv` GitHub composite action + CI jobs for lint/test/server/integration.
+
+8. **Create first vertical slice**
+   - Auth + one core domain flow (e.g. projects/tasks/budgets).
+   - Endpoint → service → provider → screen.
+   - Unit/widget/integration tests for the slice.
+
+## i18n Rules (OpenBudget pattern)
+
+- Keep ARB files under `app/lib/l10n/`.
+- Keep generated localization files under `app/lib/l10n/generated/`.
+- Use `AppLocalizations.of(context)` for all visible text.
+- Add a hardcoded-string checker script and run it in CI (`lint:l10n`).
+- Only allow explicit opt-outs with inline comment markers (for rare cases).
+
+Minimal `l10n.yaml` baseline:
+
+```yaml
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+output-dir: lib/l10n/generated
+output-class: AppLocalizations
+nullable-getter: false
+```
+
+## Routing Rules (OpenBudget pattern)
+
+- Keep route names and paths in one constants file.
+- Keep router creation inside a provider (`@riverpod GoRouter appRouter(Ref ref)`).
+- Keep redirect logic in a separate helper for easy unit tests.
+- For tabbed apps, use `StatefulShellRoute.indexedStack` with one navigator key per tab.
+- Keep non-tab overlays outside shell branches.
+
+## Provider + UI Rules
+
+- Use feature-oriented modules.
+- Follow flow: **endpoint/service (server)** → **client call** → **provider** → **UI widget**.
+- Keep side effects in providers/services, not in build methods.
+- Handle async UI with `AsyncValue.when` or pattern matching.
+
+## devenv + Commands Contract
+
+Include scripts equivalent to these responsibilities:
+
+- `server:start`
+- `runner:build`
+- `runner:serverpod`
+- `lint:analyze`
+- `lint:l10n`
+- `lint:all`
+- `test:flutter`
+- `test:all`
+
+Target dev loop:
+
+```bash
+devenv shell
+dart pub get
+runner:build
+runner:serverpod
+devenv up
+```
+
+## CI Contract
+
+At minimum, CI should run:
+
+1. lint job (`lint:all`)
+2. test job (Flutter + Dart/server tests)
+3. server job with Postgres/Redis services
+4. integration job (if integration tests exist)
+
+Use a reusable setup action to install Nix/devenv, cache pub deps, and install Flutter via FVM.
+
+## Feature Delivery Checklist (for agents)
+
+Before marking work complete:
+
+- [ ] Codegen run (Riverpod/build_runner + Serverpod)
+- [ ] Generated files committed
+- [ ] No hardcoded UI text
+- [ ] New routes declared in `route_names.dart`
+- [ ] Router/auth redirect tests updated
+- [ ] Provider tests + widget tests added/updated
+- [ ] Server endpoint/service tests added/updated
+- [ ] `lint:all` and relevant tests passing
+
+## What to produce when user asks for a "new MVP"
+
+Always produce:
+
+1. full folder skeleton,
+2. root workspace config (`pubspec.yaml` + melos scripts),
+3. app bootstrap + router + localization scaffolding,
+4. serverpod config + initial endpoint/service,
+5. devenv + CI baseline,
+6. one implemented end-to-end feature slice with tests.

package/skills/rust-workspace-bootstrap/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: rust-workspace-bootstrap
+description:
+  Scaffold a production-ready Rust workspace with knope changesets, devenv, and GitHub Actions CI/release workflows. Use when starting a new Rust project or monorepo.
+---
+
+# Rust Workspace Bootstrap
+
+Generate a Rust workspace template inspired by the release/devenv/workflow structure used in
+`mdt` and `pina`.
+
+## What it scaffolds
+
+- Cargo workspace with `core` + `cli` crates
+- `knope.toml` with:
+  - `document-change`
+  - `release`
+  - `forced-release`
+  - `publish`
+- `.changeset/` folder for change files
+- `devenv.nix`, `devenv.yaml`, `.envrc`
+- GitHub Actions:
+  - CI
+  - coverage
+  - semver checks
+  - release preview
+  - release assets
+  - docs-pages deployment
+- Opinionated defaults for `rustfmt`, `clippy`, `deny`, `dprint`
+
+## Usage
+
+```bash
+# Minimal
+{baseDir}/scaffold.js --name acme-tool
+
+# Recommended (in a separate worktree)
+git worktree add ../acme-tool -b feat/bootstrap-acme-tool
+cd ../acme-tool
+/path/to/rust-workspace-bootstrap/scaffold.js \
+  --name acme-tool \
+  --owner your-github-org \
+  --repo acme-tool \
+  --description "CLI + core Rust workspace"
+```
+
+## Options
+
+- `--name <kebab-case>` (required)
+- `--dir <path>` (optional, default: `./<name>`)
+- `--owner <github-owner>` (optional, default: `your-github-org`)
+- `--repo <github-repo>` (optional, default: `<name>`)
+- `--description <text>` (optional)
+- `--force` (optional, allow writing into non-empty directory)
+
+## Rules
+
+- Always use `_` (underscore) separators in Rust crate names.
+- Do **not** use `-` in crate package names. Example: `acme_tool_core`, not `acme-tool-core`.
+
+## After scaffolding
+
+```bash
+cd <project>
+
+direnv allow
+# or
+# devenv shell
+
+install:cargo:bin
+build:all
+lint:all
+test:all
+```
+
+Create your first changeset:
+
+```bash
+knope document-change
+```
+
+Dry-run a release:
+
+```bash
+knope release --dry-run
+```

package/skills/rust-workspace-bootstrap/scaffold.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+function printUsage() {
+	console.log(`
+Rust Workspace Bootstrap
+
+Usage:
+  scaffold.js --name <project-name> [options]
+
+Options:
+  --name <kebab-case>       Required project name.
+  --dir <path>              Target directory (default: ./<name>).
+  --owner <github-owner>    GitHub org/user (default: your-github-org).
+  --repo <github-repo>      GitHub repo name (default: <name>).
+  --description <text>      Workspace description.
+  --force                   Allow writing into a non-empty target directory.
+  --help                    Show this help.
+`);
+}
+
+function parseArgs(argv) {
+	const options = {
+		name: "",
+		dir: "",
+		owner: "your-github-org",
+		repo: "",
+		description: "",
+		force: false,
+		help: false,
+	};
+
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "--help" || arg === "-h") {
+			options.help = true;
+			continue;
+		}
+		if (arg === "--force") {
+			options.force = true;
+			continue;
+		}
+
+		if (arg.startsWith("--")) {
+			const key = arg.slice(2);
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) {
+				throw new Error(`Missing value for option: ${arg}`);
+			}
+			index += 1;
+
+			switch (key) {
+				case "name":
+					options.name = value;
+					break;
+				case "dir":
+					options.dir = value;
+					break;
+				case "owner":
+					options.owner = value;
+					break;
+				case "repo":
+					options.repo = value;
+					break;
+				case "description":
+					options.description = value;
+					break;
+				default:
+					throw new Error(`Unknown option: ${arg}`);
+			}
+			continue;
+		}
+
+		if (!options.name) {
+			options.name = arg;
+		}
+	}
+
+	return options;
+}
+
+function toTitleCase(value) {
+	return value
+		.split("-")
+		.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+		.join(" ");
+}
+
+function collectFiles(rootDir, currentDir = rootDir) {
+	const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+	const files = [];
+
+	for (const entry of entries) {
+		const absolutePath = path.join(currentDir, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...collectFiles(rootDir, absolutePath));
+			continue;
+		}
+		if (entry.isFile()) {
+			files.push(path.relative(rootDir, absolutePath));
+		}
+	}
+
+	return files;
+}
+
+function applyTokens(input, tokens) {
+	let output = input;
+	for (const [token, value] of Object.entries(tokens)) {
+		output = output.split(token).join(value);
+	}
+	return output;
+}
+
+function ensureTargetDirectory(targetDir, force) {
+	if (!fs.existsSync(targetDir)) {
+		fs.mkdirSync(targetDir, { recursive: true });
+		return;
+	}
+
+	const currentFiles = fs.readdirSync(targetDir);
+	if (currentFiles.length > 0 && !force) {
+		throw new Error(
+			`Target directory is not empty: ${targetDir}\nUse --force if you want to scaffold into an existing directory.`,
+		);
+	}
+}
+
+function main() {
+	const options = parseArgs(process.argv.slice(2));
+	if (options.help) {
+		printUsage();
+		return;
+	}
+
+	if (!options.name) {
+		printUsage();
+		throw new Error("Project name is required. Pass --name <project-name>.");
+	}
+
+	if (!/^[a-z][a-z0-9-]*$/.test(options.name)) {
+		throw new Error("Project name must be kebab-case (letters, numbers, dashes). Example: acme-tool");
+	}
+
+	const projectName = options.name;
+	const projectTitle = toTitleCase(projectName);
+	const cratePrefix = projectName.replace(/-/g, "_");
+	const coreCrate = `${cratePrefix}_core`;
+	const cliCrate = `${cratePrefix}_cli`;
+	const targetDir = path.resolve(options.dir || projectName);
+	const owner = options.owner;
+	const repo = options.repo || projectName;
+	const description = options.description || `${projectTitle} Rust workspace`;
+
+	const tokens = {
+		"__PROJECT_NAME__": projectName,
+		"__PROJECT_TITLE__": projectTitle,
+		"__CORE_CRATE__": coreCrate,
+		"__CLI_CRATE__": cliCrate,
+		"__GITHUB_OWNER__": owner,
+		"__GITHUB_REPO__": repo,
+		"__DESCRIPTION__": description,
+	};
+
+	const currentFile = fileURLToPath(import.meta.url);
+	const baseDir = path.dirname(currentFile);
+	const templateDir = path.join(baseDir, "template");
+
+	if (!fs.existsSync(templateDir)) {
+		throw new Error(`Template directory not found: ${templateDir}`);
+	}
+
+	ensureTargetDirectory(targetDir, options.force);
+
+	const templateFiles = collectFiles(templateDir);
+	const writtenFiles = [];
+
+	for (const relativeTemplatePath of templateFiles) {
+		const sourcePath = path.join(templateDir, relativeTemplatePath);
+		const targetRelativePath = applyTokens(relativeTemplatePath, tokens);
+		const destinationPath = path.join(targetDir, targetRelativePath);
+		const sourceContent = fs.readFileSync(sourcePath, "utf8");
+		const destinationContent = applyTokens(sourceContent, tokens);
+
+		fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+		fs.writeFileSync(destinationPath, destinationContent, "utf8");
+
+		if (destinationPath.endsWith(".sh")) {
+			fs.chmodSync(destinationPath, 0o755);
+		}
+
+		writtenFiles.push(targetRelativePath);
+	}
+
+	writtenFiles.sort();
+
+	console.log(`\n✅ Scaffolding complete: ${targetDir}`);
+	console.log(`   Project:      ${projectName}`);
+	console.log(`   Core crate:   ${coreCrate}`);
+	console.log(`   CLI crate:    ${cliCrate}`);
+	console.log(`   GitHub repo:  ${owner}/${repo}`);
+	console.log(`   Files:        ${writtenFiles.length}`);
+	console.log("\nNext steps:");
+	console.log(`  cd ${targetDir}`);
+	console.log("  direnv allow  # or: devenv shell");
+	console.log("  install:cargo:bin");
+	console.log("  lint:all && test:all && build:all");
+	console.log("  knope document-change");
+	console.log("  knope release --dry-run\n");
+}
+
+try {
+	main();
+} catch (error) {
+	const message = error instanceof Error ? error.message : String(error);
+	console.error(`\n❌ ${message}\n`);
+	process.exit(1);
+}

package/skills/rust-workspace-bootstrap/template/.cargo/config.toml

@@ -0,0 +1,7 @@
+[alias]
+deny = ["bin", "cargo-deny"]
+insta = ["bin", "cargo-insta"]
+llvm-cov = ["bin", "cargo-llvm-cov"]
+nextest = ["bin", "cargo-nextest"]
+semver-checks = ["bin", "cargo-semver-checks"]
+workspaces = ["bin", "cargo-workspaces"]

package/skills/rust-workspace-bootstrap/template/.envrc

@@ -0,0 +1,7 @@
+export DIRENV_WARN_TIMEOUT=20s
+
+eval "$(devenv direnvrc)"
+
+# The use_devenv function supports passing flags to the devenv command
+# For example: use devenv --impure --option services.postgres.enable:bool true
+use devenv -c

package/skills/rust-workspace-bootstrap/template/.github/actions/devenv/action.yml

@@ -0,0 +1,42 @@
+name: devenv
+description: Setup development environment with devenv
+inputs:
+  github-token:
+    description: Provide a GitHub token
+    required: true
+  cache-version:
+    description: Cache version for dependency keys
+    required: false
+    default: "v1"
+
+runs:
+  using: composite
+  steps:
+    - name: cache rust dependencies
+      uses: Swatinem/rust-cache@v2
+      with:
+        prefix-key: "${{ inputs.cache-version }}"
+
+    - name: cache cargo binaries
+      uses: actions/cache@v4
+      with:
+        path: ./.bin
+        key: ${{ runner.os }}-cargo-bin-${{ inputs.cache-version }}-${{ env.RUSTUP_TOOLCHAIN }}-${{ hashFiles('rust-toolchain.toml', 'Cargo.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-cargo-bin-${{ inputs.cache-version }}-
+
+    - name: install nix
+      uses: cachix/install-nix-action@v31
+      with:
+        github_access_token: ${{ inputs.github-token }}
+
+    - name: setup nix environment
+      run: |
+        nix profile add --accept-flake-config nixpkgs#cachix
+        cachix use devenv
+        nix profile add nixpkgs#devenv
+      shell: bash
+
+    - name: install dependencies
+      run: install:cargo:bin
+      shell: devenv shell -- bash -e {0}

package/skills/rust-workspace-bootstrap/template/.github/workflows/ci.yml

@@ -0,0 +1,130 @@
+name: "ci"
+permissions:
+  contents: read
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  commit-lint:
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: validate commit messages
+        run: |
+          PATTERN='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+'
+
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE_SHA='${{ github.event.pull_request.base.sha }}'
+            HEAD_SHA='${{ github.event.pull_request.head.sha }}'
+            COMMITS=$(git log --format='%s' --no-merges "${BASE_SHA}..${HEAD_SHA}")
+          else
+            COMMITS=$(git log --format='%s' -1)
+          fi
+
+          FAILED=0
+          while IFS= read -r msg; do
+            [ -z "$msg" ] && continue
+            if ! echo "$msg" | grep -qE "$PATTERN"; then
+              echo "::error::Invalid commit message: '$msg'"
+              FAILED=1
+            fi
+          done <<< "$COMMITS"
+
+          if [ "$FAILED" -eq 1 ]; then
+            exit 1
+          fi
+
+  changeset:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' || !startsWith(github.event.head_commit.message, 'chore: prepare releases')
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v4
+
+      - name: check for changeset
+        run: |
+          CHANGESETS=$(find .changeset -name '*.md' ! -name 'README.md' 2>/dev/null | wc -l | tr -d ' ')
+          if [ "$CHANGESETS" -eq 0 ]; then
+            echo "::error::No changeset found. Run 'knope document-change'."
+            exit 1
+          fi
+          echo "✅ Found $CHANGESETS changeset(s)"
+
+  lint:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v4
+
+      - name: setup
+        uses: ./.github/actions/devenv
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: lint
+        run: lint:all
+        shell: devenv shell -c -- bash -e {0}
+
+  test:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v4
+
+      - name: setup
+        uses: ./.github/actions/devenv
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: run tests
+        run: test:all
+        shell: devenv shell -c -- bash -e {0}
+
+  build:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    needs: [commit-lint, changeset, lint, test]
+    if: ${{ !failure() && !cancelled() }}
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v4
+
+      - name: setup
+        uses: ./.github/actions/devenv
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: build default features
+        run: build:default
+        shell: devenv shell -c -- bash -e {0}
+
+      - name: build all features
+        run: build:all
+        shell: devenv shell -c -- bash -e {0}
+
+  security:
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v4
+
+      - name: run cargo-deny
+        uses: EmbarkStudios/cargo-deny-action@v2