@planview/pvds-skills 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +156 -0
  2. package/dist/cli.js +15361 -0
  3. package/dist/cli.js.map +1 -0
  4. package/package.json +75 -0
package/README.md ADDED
@@ -0,0 +1,156 @@
1
+ # PVDS Agent Skills & Knowledge Base
2
+
3
+ Skills and reference knowledge for building with the Planview Design System (PVDS).
4
+
5
+ ## Installation
6
+
7
+ The recommended path is the `@planview/pvds-skills` CLI, which auto-detects your project's skills root, records a `.pvds-skills/config.json` marker, and installs all three skills in one step:
8
+
9
+ ```bash
10
+ pnpm dlx @planview/pvds-skills init
11
+ ```
12
+
13
+ For npm / yarn / bun, substitute the equivalent runner (`npx --yes`, `yarn dlx`, `bunx`). The CLI is a zero-dependency ~100 KB tarball — no lockfile changes, no peer deps.
14
+
15
+ Either path installs the skills into your project's `.claude/skills/` directory (or your home directory if you install globally).
16
+
17
+ ## Available Skills
18
+
19
+ | Skill | Purpose |
20
+ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
21
+ | `pvds-knowledge` | Shared reference knowledge base — API docs, code recipes, gotchas, architecture guides. Not a standalone skill; other skills load data from it. |
22
+ | `pvds-builder` | Generate React code using PVDS packages correctly. Loads knowledge on demand to produce correct, performant, accessible code. |
23
+ | `pvds-peer-review` | Expert-level peer review of code consuming PVDS packages. Checks coding style, accessibility, performance, theming, and more. |
24
+
25
+ ## CLI reference
26
+
27
+ ```bash
28
+ pnpm dlx @planview/pvds-skills init # one-time setup + install skill markdown
29
+ pnpm dlx @planview/pvds-skills upgrade # refresh skill markdown; bump config version
30
+ pnpm dlx @planview/pvds-skills check # run all deterministic PVDS audits
31
+ pnpm dlx @planview/pvds-skills doctor # verify config + skills presence
32
+ pnpm dlx @planview/pvds-skills versions # compare bundled PVDS reference data vs. installed pv-* versions
33
+ pnpm dlx @planview/pvds-skills props <Component> # look up a component's own-declared props from the manifest
34
+ pnpm dlx @planview/pvds-skills fix # no-op (parked for future auto-fixable checks)
35
+ pnpm dlx @planview/pvds-skills --help
36
+ ```
37
+
38
+ For npm / yarn / bun projects, substitute the equivalent runner:
39
+
40
+ | PM | Run |
41
+ | ---- | ----------------------------------- |
42
+ | pnpm | `pnpm dlx @planview/pvds-skills …` |
43
+ | npm | `npx --yes @planview/pvds-skills …` |
44
+ | yarn | `yarn dlx @planview/pvds-skills …` |
45
+ | bun | `bunx @planview/pvds-skills …` |
46
+
47
+ The CLI auto-detects your project's package manager (via `packageManager` in `package.json`, then lockfile) and uses the matching runner for the downstream `skills add` invocation. Override with `--package-manager=<pnpm|npm|yarn|bun>` if detection is wrong.
48
+
49
+ ### `check` — deterministic PVDS audits
50
+
51
+ `check` walks the repo (skipping `node_modules`, `dist`, etc.) and runs a set of zero-heuristic checks against `@planview/pv-*` usage: version drift, subpath imports, orphan/undeclared dependencies (including `.less`/`.scss`/`.sass`/`.css` references), deprecated-export imports, hardcoded colors/spacing in CSS-in-JS, invalid enum prop literals, unknown/typo'd JSX props, and manifest-vs-installed version drift.
52
+
53
+ ```bash
54
+ pnpm dlx @planview/pvds-skills check
55
+ pnpm dlx @planview/pvds-skills check --verbose # list every scanned file
56
+ pnpm dlx @planview/pvds-skills check --only=hardcoded-colors,hardcoded-spacing
57
+ pnpm dlx @planview/pvds-skills check --format=json --output=./pvds-report.json
58
+ ```
59
+
60
+ Every run prints a scan summary per category so a "0 issues" result is trustworthy. Exit code is `1` when any error-level issue is found; suitable for CI. Output formats: `human` (default), `json`, `sarif`.
61
+
62
+ By default `check` walks the entire directory tree. Scope it to a specific file set instead with:
63
+
64
+ ```bash
65
+ pnpm dlx @planview/pvds-skills check --files=src/components/Button.tsx,src/components/Input.tsx
66
+ pnpm dlx @planview/pvds-skills check --changed # uncommitted changes (tracked + untracked), vs HEAD
67
+ pnpm dlx @planview/pvds-skills check --staged # staged files only (git diff --cached)
68
+ pnpm dlx @planview/pvds-skills check --since=main # files changed since diverging from a ref
69
+ ```
70
+
71
+ These are additive — combine `--files` with a git flag to union both sets. Scoping only applies to the per-file checks (`subpath-imports`, `deprecated-imports`, `hardcoded-colors`, `hardcoded-spacing`, `literal-size-props`, `unknown-props`, and the source side of `undeclared-imports`); `orphan-deps`, `versions`, and `manifest-drift` always need whole-repo visibility to be correct and ignore it.
72
+
73
+ `--changed`, `--staged`, and `--since` shell out to the `git` binary (the only external process the CLI invokes) and require the target directory to be inside a git repository — `--files` has no such requirement.
74
+
75
+ ### `versions` — reference-data freshness
76
+
77
+ The manifest baked into the CLI (deprecations, enum props, style-token hints) is generated once per release against one fixed version of each `@planview/pv-*` package — it does not track a consumer's installs over time. `versions` shows what the bundled manifest was generated against next to what's actually installed in your project, and flags major-version gaps. The same comparison runs as part of `check` under the `manifest-drift` category (warning-level, never blocks CI on its own).
78
+
79
+ ```bash
80
+ pnpm dlx @planview/pvds-skills versions
81
+ pnpm dlx @planview/pvds-skills versions --format=json
82
+ ```
83
+
84
+ ### `props` — component prop lookup
85
+
86
+ Looks up a component's own-declared props (name, type, enum values, deprecation) directly from the bundled manifest — no source scanning, no network call beyond the initial `dlx` fetch. Intended for agents (or humans) that need an authoritative prop list before writing or reviewing code, without loading the full `api-reference.md`.
87
+
88
+ ```bash
89
+ pnpm dlx @planview/pvds-skills props Grid
90
+ pnpm dlx @planview/pvds-skills props Button --package=@planview/pv-uikit
91
+ pnpm dlx @planview/pvds-skills props FilterPanel --format=json
92
+ ```
93
+
94
+ Only _own-declared_ props are tracked (see Architecture below) — a component with zero own props (fully inherited from HTML/React) won't appear, and that's not an error. Standard HTML/React/ARIA attributes (`className`, `onClick`, `style`, `data-*`, `aria-*`, ...) are always valid regardless of manifest presence; every response repeats this caveat. Exit code is `1` when the component isn't found in the manifest.
95
+
96
+ ### `--yes` (init)
97
+
98
+ `pvds-skills init` itself is non-interactive. `--yes` forwards `-y` to the downstream `skills add` command so it skips its own prompts. Use it in CI or headless runs.
99
+
100
+ ### Architecture
101
+
102
+ Single bundled ESM entry (`dist/cli.js`). Every dependency (currently just `citty`) is inlined at build time via tsup's `noExternal: /.*/`. No runtime deps, no peer deps, no post-install hooks. The consumer-facing manifest (deprecations, enum props, style-token reverse-lookups) is generated from the installed `@planview/pv-*` `.d.ts` files via `pnpm refresh-manifest` and bundled inline — no runtime dependency on those packages.
103
+
104
+ ## Usage
105
+
106
+ ### Building with PVDS
107
+
108
+ Invoke the builder skill when you need help creating UI with PVDS:
109
+
110
+ ```
111
+ /pvds-builder I need a grid with editable cells and drag-and-drop
112
+ ```
113
+
114
+ ### Reviewing PVDS code
115
+
116
+ Invoke the review skill to check your PVDS usage:
117
+
118
+ You can ask for a review of a specific PR:
119
+
120
+ ```
121
+ /pvds-peer-review can you please review PR #123
122
+ ```
123
+
124
+ Or ask for a general review of your current branch:
125
+
126
+ ```
127
+ /pvds-peer-review can you please review the current changes in my branch? The intent with the changes are....
128
+ ```
129
+
130
+ Or ask for a review of commits not yet pushed to a PR:
131
+
132
+ ```
133
+ /pvds-peer-review can you please review the last three commits in my branch? The intent with the changes are....
134
+ ```
135
+
136
+ ## Knowledge Base Coverage
137
+
138
+ | Package | Status |
139
+ | ------------------------ | ------------------------------------------------------------ |
140
+ | `@planview/pv-grid` | Available (API reference, 27 recipes, gotchas, architecture) |
141
+ | `@planview/pv-uikit` | Available (API reference, 15 recipes, gotchas, architecture) |
142
+ | `@planview/pv-utilities` | Available (API reference, 13 recipes, gotchas, architecture) |
143
+ | `@planview/pv-tokens` | Available (API reference, gotchas) |
144
+ | `@planview/pv-toolbar` | Available (API reference, 15 recipes, gotchas, architecture) |
145
+ | `@planview/pv-icons` | Available (API reference, gotchas) |
146
+ | `@planview/pv-details` | Available (API reference, 12 recipes, gotchas, architecture) |
147
+ | `@planview/pv-filter` | Available (API reference, 14 recipes, gotchas, architecture) |
148
+ | `@planview/pv-gantt` | Available (API reference, 17 recipes, gotchas, architecture) |
149
+ | `@planview/pv-form` | Available (API reference, 19 recipes, gotchas, architecture) |
150
+ | `@planview/pv-widget` | Available (API reference, 17 recipes, gotchas, architecture) |
151
+
152
+ Cross-cutting guides available: accessibility, coding style, theming & tokens, i18n, testing, performance.
153
+
154
+ ## Contributing
155
+
156
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for local development, testing, and release instructions.