shmakk 1.1.0 → 1.2.0

package/skills/general-superjson.md

@@ -0,0 +1,274 @@
+---
+name: superjson
+description: >
+  Configure SuperJSON transformer on both server initTRPC.create({ transformer:
+  superjson }) and every client terminating link (httpBatchLink, httpLink, wsLink,
+  httpSubscriptionLink) to support Date, Map, Set, BigInt over the wire. Transformer
+  must match on both sides. In v11, transformer goes on individual links, not the
+  client constructor.
+type: composition
+library: trpc
+library_version: '11.15.1'
+requires:
+  - server-setup
+  - client-setup
+sources:
+  - www/docs/server/data-transformers.md
+category: general
+---
+
+# tRPC -- SuperJSON Transformer
+
+## Setup
+
+### 1. Install superjson
+
+```bash
+npm install superjson
+```
+
+### 2. Add to initTRPC on the server
+
+```ts
+// server/trpc.ts
+import { initTRPC } from '@trpc/server';
+import superjson from 'superjson';
+
+const t = initTRPC.create({
+  transformer: superjson,
+});
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+```
+
+### 3. Add to every terminating link on the client
+
+```ts
+// client.ts
+import { createTRPCClient, httpBatchLink } from '@trpc/client';
+import superjson from 'superjson';
+import type { AppRouter } from './server/trpc';
+
+const client = createTRPCClient<AppRouter>({
+  links: [
+    httpBatchLink({
+      url: 'http://localhost:3000/trpc',
+      transformer: superjson,
+    }),
+  ],
+});
+```
+
+Now Date, Map, Set, BigInt, RegExp, undefined, and other non-JSON types survive the round trip.
+
+## Core Patterns
+
+### SuperJSON with splitLink and Subscriptions
+
+```ts
+import {
+  createTRPCClient,
+  httpBatchLink,
+  httpSubscriptionLink,
+  splitLink,
+} from '@trpc/client';
+import superjson from 'superjson';
+import type { AppRouter } from './server/trpc';
+
+const client = createTRPCClient<AppRouter>({
+  links: [
+    splitLink({
+      condition: (op) => op.type === 'subscription',
+      true: httpSubscriptionLink({
+        url: 'http://localhost:3000/trpc',
+        transformer: superjson,
+      }),
+      false: httpBatchLink({
+        url: 'http://localhost:3000/trpc',
+        transformer: superjson,
+      }),
+    }),
+  ],
+});
+```
+
+Every terminating link in every branch must have `transformer: superjson`.
+
+### SuperJSON with wsLink
+
+```ts
+import { createTRPCClient, createWSClient, wsLink } from '@trpc/client';
+import superjson from 'superjson';
+import type { AppRouter } from './server/trpc';
+
+const wsClient = createWSClient({
+  url: 'ws://localhost:3000',
+});
+
+const client = createTRPCClient<AppRouter>({
+  links: [
+    wsLink<AppRouter>({
+      client: wsClient,
+      transformer: superjson,
+    }),
+  ],
+});
+```
+
+### Returning Dates from Procedures
+
+```ts
+// server
+import { z } from 'zod';
+import { publicProcedure, router } from './trpc';
+
+const appRouter = router({
+  getEvent: publicProcedure
+    .input(z.object({ id: z.string() }))
+    .query(({ input }) => {
+      return {
+        id: input.id,
+        name: 'Launch Party',
+        date: new Date('2025-01-01T00:00:00Z'),
+      };
+    }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+```ts
+// client
+const event = await client.getEvent.query({ id: '1' });
+console.log(event.date instanceof Date); // true
+console.log(event.date.getFullYear()); // 2025
+```
+
+Without superjson, `event.date` would be a string like `"2025-01-01T00:00:00.000Z"`.
+
+## Common Mistakes
+
+### [CRITICAL] Transformer on server but missing from client link
+
+Wrong:
+
+```ts
+// Server
+const t = initTRPC.create({ transformer: superjson });
+
+// Client
+const client = createTRPCClient<AppRouter>({
+  links: [httpBatchLink({ url: 'http://localhost:3000/trpc' })],
+});
+```
+
+Correct:
+
+```ts
+// Server
+const t = initTRPC.create({ transformer: superjson });
+
+// Client
+const client = createTRPCClient<AppRouter>({
+  links: [
+    httpBatchLink({
+      url: 'http://localhost:3000/trpc',
+      transformer: superjson,
+    }),
+  ],
+});
+```
+
+Server encodes with superjson but client tries to parse raw JSON, causing "Unable to transform response" or garbled data.
+
+Source: www/docs/server/data-transformers.md
+
+### [CRITICAL] Transformer goes on individual links, not createTRPCClient
+
+The `transformer` option is on individual terminating links:
+
+```ts
+createTRPCClient<AppRouter>({
+  links: [
+    httpBatchLink({
+      url: 'http://localhost:3000/trpc',
+      transformer: superjson,
+    }),
+  ],
+});
+```
+
+In v11, `transformer` was moved from the client constructor to individual links. Passing it to `createTRPCClient` throws a TypeError.
+
+Source: packages/client/src/internals/TRPCUntypedClient.ts
+
+### [CRITICAL] Transformer on only some terminating links in splitLink
+
+Wrong:
+
+```ts
+splitLink({
+  condition: (op) => op.type === 'subscription',
+  true: httpSubscriptionLink({
+    url: 'http://localhost:3000/trpc',
+    // missing transformer!
+  }),
+  false: httpBatchLink({
+    url: 'http://localhost:3000/trpc',
+    transformer: superjson,
+  }),
+});
+```
+
+Correct:
+
+```ts
+splitLink({
+  condition: (op) => op.type === 'subscription',
+  true: httpSubscriptionLink({
+    url: 'http://localhost:3000/trpc',
+    transformer: superjson,
+  }),
+  false: httpBatchLink({
+    url: 'http://localhost:3000/trpc',
+    transformer: superjson,
+  }),
+});
+```
+
+Every terminating link must have the same transformer. A missing transformer on one branch causes deserialization failures only for operations routed through that branch.
+
+Source: www/docs/server/data-transformers.md
+
+### [HIGH] Using transformer on client but not on server
+
+Wrong:
+
+```ts
+// Server -- no transformer
+const t = initTRPC.create();
+
+// Client
+httpBatchLink({ url, transformer: superjson });
+```
+
+Correct:
+
+```ts
+// Server
+const t = initTRPC.create({ transformer: superjson });
+
+// Client
+httpBatchLink({ url, transformer: superjson });
+```
+
+The transformer must be configured on both `initTRPC.create()` and every client link. Client-only transformer corrupts the request encoding because the server expects plain JSON.
+
+Source: www/docs/server/data-transformers.md
+
+## See Also
+
+- `client-setup` -- create the tRPC client and configure links
+- `links` -- detailed options for each link type including transformer
+- `server-setup` -- initTRPC.create() where the server transformer is configured

package/skills/general-swiftpm-macos.md

@@ -0,0 +1,51 @@
+---
+name: swiftpm-macos
+description: Build, run, and test pure SwiftPM-based macOS packages and executables. Use when the repo is package-first, when there is no Xcode project, or when Swift package workflows are the fastest path to diagnosis.
+category: general
+---
+
+# SwiftPM for macOS
+
+## Quick Start
+
+Use this skill when `Package.swift` is the primary entrypoint or when SwiftPM is
+the fastest path to a reproducible result.
+
+## Workflow
+
+1. Inspect the package.
+   - Read `Package.swift`.
+   - Identify executable, library, and test products.
+
+2. Build with SwiftPM.
+   - Use `swift build` by default.
+   - Use release mode only when the user explicitly needs it.
+
+3. Run the right product.
+   - Use `swift run <product>` when an executable exists.
+   - If multiple executables exist, explain the default choice.
+
+4. Test narrowly.
+   - Use `swift test`.
+   - Apply filters when a specific test target or case is known.
+
+5. Summarize failures.
+   - Module/import resolution
+   - Package graph or dependency issue
+   - Linker failure
+   - Runtime failure
+   - Test regression
+
+## Guardrails
+
+- Prefer SwiftPM over Xcode when both exist and the package path is clearly simpler.
+- Do not assume an app bundle exists in a pure package workflow.
+- Explain when the package is library-only and therefore not directly runnable.
+
+## Output Expectations
+
+Provide:
+- the package products you found
+- the command you ran
+- whether build, run, or test succeeded
+- the top blocker if not

package/skills/general-threat-model.md

@@ -0,0 +1,61 @@
+---
+name: threat-model
+description: Use when Codex is already in the threat-modeling phase of a security scan, the user explicitly invokes $threat-model, or the user explicitly asks to create, update, or persist a repository threat model. Do not use as the primary trigger for full PR, commit, branch, patch, or repository scans.
+metadata:
+  short-description: Build a repository threat model
+category: general
+---
+
+# Security Threat Model
+
+## Objective
+
+Establish the repository-scoped threat model at the path defined in `../../references/scan-artifacts.md`. If this already exists, stop here. If a threat model or clearly authoritative security scan guidance is provided or already exists, persist it unchanged to this file, then stop here.
+
+`AGENTS.md` can be that authoritative source when it is sufficiently specific about the repository's product surfaces, trust boundaries, attacker-controlled inputs, assumptions, or security scan guidance to serve as the threat model.
+
+If no threat model is provided, generate a repository-scoped threat model to be used in future bug discovery. The threat model should holistically cover the entire repository and should make it obvious:
+
+- what assets or privileges matter
+- what trust boundaries exist
+- what inputs are attacker-controlled
+- what invariants the code must preserve
+- what repository-wide failure modes would matter most
+
+## Artifact Resolution
+
+The path references in this skill are the default locations for this phase.
+If the user explicitly provides a different path for a required input or output, use the user-provided path instead of the corresponding default path referenced in this skill.
+If a required input is still missing, stop and ask the user for it before continuing.
+Use the shared scan artifact path conventions in `../../references/scan-artifacts.md`.
+
+## Workflow
+
+1. Resolve `repo_name`, `security_scans_dir`, and the repository-scoped threat model path using `../../references/scan-artifacts.md`.
+2. If the repository-scoped threat model already exists, stop here.
+3. If a threat model or authoritative security scan guidance is provided or referenced:
+   - write it exactly to the repository-scoped threat model path
+   - treat that file as the only threat model source of truth
+   - do not expand, summarize, or reinterpret it
+   - `AGENTS.md` is acceptable here when it is clearly being used as the security scan guidance or threat model source for this scan and is sufficiently repository-specific to stand in for a threat model
+4. Otherwise, generate a repository-scoped threat model using the checklist below.
+5. Before finalizing this phase, sanity-check that:
+   - the threat model is repository-scoped rather than being centered around any specific scan target
+   - it describes repository-wide primary product or runtime surfaces and trust boundaries before covering any narrower examples
+   - any vulnerability-class discussion is about repository-context classes, not findings about any current diff
+6. Write the exact threat model to the repository-scoped threat model path.
+
+## Threat Model Generation Guidance
+
+Generate and structure the threat model using `references/threat-model-guidance.md`.
+
+## Hard Rules
+
+- A provided threat model or authoritative security scan guidance is authoritative.
+- Threat model generation must stay at repository scope unless the user explicitly asks for narrower scope.
+- Do not turn this phase into findings about any current diff.
+- Do not let the current scan target, touched subsystem, or changed directories become the center of gravity for this phase unless the user explicitly asks for that narrower scope.
+- In large monorepos, avoid centering `personal/`, `test/`, `tests/`, `docs/`, `examples/`, or one-off developer tooling unless repository evidence shows those are real deployed or privileged workflow surfaces.
+- Call out trust boundaries and assumptions explicitly.
+- Keep references to vulnerability types at the level of repository-context classes, rather than any diff findings.
+- Persist the threat model output to the repository-scoped threat model path from `../../references/scan-artifacts.md`.

package/skills/invoices.md

@@ -0,0 +1,167 @@
+---
+name: invoices
+version: 1
+category: business
+---
+
+# Invoice Generation
+
+Create professional invoices in PDF or markdown format from a template and line items.
+
+## When to use this skill
+
+- User wants to create an invoice for a client
+- User wants to generate a recurring invoice
+- User asks about billing, invoicing, payment request
+- User mentions "invoice", "bill the client", "send invoice"
+
+## Prerequisites
+
+```
+which pandoc wkhtmltopdf 2>/dev/null
+```
+
+- `pandoc` — converts markdown to PDF (via LaTeX or wkhtmltopdf)
+- `wkhtmltopdf` — HTML to PDF (alternative to LaTeX for simpler output)
+
+If neither: create a clean markdown file the user can export manually.
+
+## Procedure
+
+### Step 1: Gather invoice details
+
+Ask the user for (or infer from context):
+- **Your info**: name/company, address, email, payment details (bank, PayPal, etc.)
+- **Client info**: client name/company, address
+- **Invoice number**: use a sequential numbering scheme (INV-2024-001)
+- **Issue date and due date** (typically net 30 days)
+- **Line items**: description, quantity, unit price
+- **Tax rate** (if applicable)
+- **Notes** (payment instructions, late fees, etc.)
+
+### Step 2: Calculate totals
+
+```python
+items = [
+    {"description": "Website development", "qty": 1, "unit": 5000},
+    {"description": "Hosting setup", "qty": 1, "unit": 200},
+    {"description": "Monthly maintenance", "qty": 3, "unit": 150},
+]
+
+subtotal = sum(item["qty"] * item["unit"] for item in items)
+tax_rate = 0.20  # 20% VAT
+tax = subtotal * tax_rate
+total = subtotal + tax
+```
+
+### Step 3: Generate invoice markdown
+
+Write to `invoices/INV-2024-001.md`:
+
+```markdown
+# INVOICE
+
+**From:**
+Marcus Bader
+123 Main Street, Stockholm, Sweden
+marcus@example.com
+
+**To:**
+Client Company Name
+456 Client Street, London, UK
+billing@client.com
+
+---
+
+| | |
+|---|---|
+| **Invoice #** | INV-2024-001 |
+| **Issue Date** | 15 January 2024 |
+| **Due Date** | 14 February 2024 |
+| **Status** | Due |
+
+---
+
+## Services
+
+| Description | Qty | Unit Price | Total |
+|---|---|---|---|
+| Website development | 1 | €5,000.00 | €5,000.00 |
+| Hosting setup | 1 | €200.00 | €200.00 |
+| Monthly maintenance | 3 | €150.00 | €450.00 |
+
+---
+
+| | |
+|---|---|
+| **Subtotal** | €5,650.00 |
+| **VAT (20%)** | €1,130.00 |
+| **Total Due** | **€6,780.00** |
+
+---
+
+## Payment Details
+
+Bank: Example Bank
+IBAN: SE00 0000 0000 0000 0000
+BIC: EXAMPLEXX
+
+Please reference invoice number **INV-2024-001** with your payment.
+
+Late payments are subject to 1.5% monthly interest after due date.
+```
+
+### Step 4: Convert to PDF
+
+With pandoc + wkhtmltopdf:
+```
+pandoc INV-2024-001.md -o INV-2024-001.pdf --pdf-engine=wkhtmltopdf
+```
+
+With pandoc + LaTeX (better typography):
+```
+pandoc INV-2024-001.md -o INV-2024-001.pdf
+```
+
+With a CSS stylesheet for better styling:
+```
+pandoc INV-2024-001.md -o INV-2024-001.pdf --pdf-engine=wkhtmltopdf --css=invoice.css
+```
+
+### Step 5: Track invoice
+
+Update an invoice log file (`~/invoices/log.csv`):
+```
+date,invoice_no,client,amount,status,due_date
+2024-01-15,INV-2024-001,Client Company,6780.00,sent,2024-02-14
+```
+
+## Output format
+
+After creating the invoice, summarize:
+```
+INVOICE CREATED: INV-2024-001
+
+Client:    Client Company Name
+Amount:    €6,780.00 (incl. 20% VAT)
+Due:       14 February 2024
+
+Files:
+  Markdown: ~/invoices/INV-2024-001.md
+  PDF:      ~/invoices/INV-2024-001.pdf
+
+Next steps:
+• Send PDF to billing@client.com
+• Log entry added to ~/invoices/log.csv
+```
+
+## Pitfalls
+
+- Always confirm the amounts with the user before generating PDF
+- Use the same invoice numbering scheme consistently — don't restart the sequence
+- Keep copies of all invoices (don't overwrite)
+- For international clients, be clear about currency; for EU B2B, include VAT numbers
+
+## Verification
+
+After generating: open/read the PDF or markdown to verify totals are correct before sending.

package/skills/licenses.md

@@ -0,0 +1,159 @@
+---
+name: licenses
+version: 1
+category: business
+---
+
+# Software License Analysis
+
+Analyze dependency licenses for compatibility, generate NOTICE files, and flag compliance risks.
+
+## When to use this skill
+
+- User wants to know what licenses their dependencies use
+- User wants to check if licenses are compatible with their project's license
+- User wants to generate a NOTICE or ATTRIBUTIONS file
+- User is preparing for open-source release or commercial distribution
+- User mentions "license", "GPL", "MIT", "open source compliance", "attribution"
+
+## License Compatibility Quick Reference
+
+| Dependency License | Can use in MIT project? | Can use in commercial closed-source? |
+|-------------------|------------------------|-------------------------------------|
+| MIT               | ✅ Yes                  | ✅ Yes (attribution required)        |
+| ISC               | ✅ Yes                  | ✅ Yes (attribution required)        |
+| Apache-2.0        | ✅ Yes                  | ✅ Yes (attribution + NOTICE required)|
+| BSD-2/3-Clause    | ✅ Yes                  | ✅ Yes (attribution required)        |
+| MPL-2.0           | ⚠️ Check               | ⚠️ Modified MPL files must stay open |
+| LGPL-2.1/3.0      | ⚠️ Check               | ⚠️ OK if dynamically linked, complex otherwise |
+| GPL-2.0/3.0       | ❌ Copyleft             | ❌ Forces project to go GPL          |
+| AGPL-3.0          | ❌ Strong copyleft      | ❌ Also covers network use           |
+| CC-BY-SA          | ❌ For data/content     | ❌ Copyleft, requires same license   |
+| Proprietary       | ❌ Check terms          | ❌ Need commercial license           |
+
+## Procedure
+
+### Step 1: Extract all dependency licenses
+
+**npm / Node.js:**
+```
+npx license-checker --json --out licenses.json
+npx license-checker --summary
+npx license-checker --csv --out licenses.csv
+```
+
+**Python:**
+```
+pip install pip-licenses 2>/dev/null
+pip-licenses --format=json --output-file=licenses.json
+pip-licenses --format=table
+```
+
+**Go:**
+```
+go-licenses report ./... 2>/dev/null
+# or: golicense .
+```
+
+**Cargo (Rust):**
+```
+cargo license
+cargo license --json
+```
+
+### Step 2: Check for problematic licenses
+
+**npm — fail on copyleft:**
+```
+npx license-checker --failOn "GPL-2.0;GPL-3.0;AGPL-3.0;LGPL-2.1;LGPL-3.0"
+```
+
+**Scan the output JSON for anything that isn't in the safe list:**
+
+Safe licenses (permissive): MIT, ISC, BSD-2-Clause, BSD-3-Clause, Apache-2.0, CC0-1.0, Unlicense, 0BSD
+
+Review carefully: MPL-2.0, LGPL-*, CC-BY-*, EUPL-1.2
+
+Red flag: GPL-*, AGPL-*, CC-BY-SA-*, SSPL
+
+### Step 3: Investigate "Unknown" licenses
+
+For packages with unknown or unusual licenses:
+1. Find the package's repository URL
+2. Look for a LICENSE or COPYING file in the repo root
+3. Identify the license and add it to your records
+
+### Step 4: Generate NOTICE / ATTRIBUTIONS file
+
+For projects using Apache-licensed dependencies (required) or for general attribution:
+
+```python
+import json
+
+with open('licenses.json') as f:
+    deps = json.load(f)
+
+lines = ["THIRD-PARTY SOFTWARE NOTICES\n", "=" * 40 + "\n\n"]
+for name, info in sorted(deps.items()):
+    lines.append(f"Package: {name}\n")
+    if info.get('licenseFile'):
+        lines.append(f"License: {info.get('licenses', 'Unknown')}\n")
+        lines.append(f"Repository: {info.get('repository', 'N/A')}\n")
+    lines.append("\n")
+
+with open('NOTICE', 'w') as f:
+    f.writelines(lines)
+```
+
+### Step 5: For LGPL dependencies
+
+LGPL is acceptable IF:
+- You dynamically link to the library (not statically embed it)
+- You allow users to relink with a modified version of the library
+- You include a copy of the LGPL license text
+
+Verify your build system uses dynamic linking for LGPL packages.
+
+## Output format
+
+```
+LICENSE ANALYSIS: my-project (MIT)
+
+SUMMARY
+  Total packages: 142
+  License types:  MIT (89), ISC (23), Apache-2.0 (18), BSD-3-Clause (8), Other (4)
+
+✅ COMPATIBLE — No action needed
+  MIT, ISC, BSD-*, Apache-2.0 packages are all compatible with MIT license.
+
+⚠️  REVIEW REQUIRED
+  • lodash-addons@2.4.2 — license: "Unlicense" — generally permissive, but verify.
+  • uuid-tool@1.0.0 — license listed as "WTFPL" — effectively public domain, but
+    double-check company policy.
+
+❌ POTENTIAL ISSUES
+  • analytics-lib@3.1.0 — GPL-3.0 — INCOMPATIBLE with closed-source commercial use.
+    Alternatives: consider mixpanel-browser (MIT) or custom implementation.
+
+REQUIRED ATTRIBUTIONS
+  Apache-2.0 packages require inclusion of NOTICE file in distributions:
+  • typescript-eslint@6.0.0 (Apache-2.0)
+  • @aws-sdk/client-s3@3.0.0 (Apache-2.0)
+
+ACTION ITEMS
+1. Replace analytics-lib with a MIT/Apache-2.0 alternative
+2. Generate NOTICE file before next commercial release
+3. Verify Unlicense/WTFPL packages are acceptable under company IP policy
+```
+
+## Pitfalls
+
+- "MIT OR Apache-2.0" means you can choose either — pick MIT for simplicity
+- Some packages declare one license in package.json but include a different LICENSE file — the file takes precedence
+- LGPL compliance is complex: consult legal counsel for commercial products that embed LGPL libraries
+- This analysis informs decisions but is not legal advice — for significant commercial products, have a lawyer review
+
+## Verification
+
+After generating NOTICE file: verify it includes entries for all Apache-2.0 packages (which require it).
+Cross-check the flagged GPL packages actually appear in `npm ls` to confirm they're truly in your dependency tree (not just listed in package.json but tree-shaken).