@puffinstudio/fizzyx 1.3.0 → 1.4.0
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.
- package/README.md +63 -14
- package/THIRD-PARTY-NOTICES.md +93 -0
- package/dist/main.js +692 -637
- package/package.json +87 -80
package/README.md
CHANGED
|
@@ -263,6 +263,9 @@ Options:
|
|
|
263
263
|
|
|
264
264
|
If `--input`/`--output`/`--client` are omitted, values from `.fizzyx.yaml` `openapi[0]` are used.
|
|
265
265
|
|
|
266
|
+
Pass raw values to generated path-parameter arguments. Generated clients percent-encode each
|
|
267
|
+
dynamic path segment once; query parameters continue to use the target runtime's query serializer.
|
|
268
|
+
|
|
266
269
|
Output is 3 files — runtime, types, and tree-shakeable endpoint functions:
|
|
267
270
|
|
|
268
271
|
```
|
|
@@ -276,6 +279,8 @@ src/api/
|
|
|
276
279
|
|
|
277
280
|
Generate a standalone shadcn admin project with a typed fetch client and TanStack Query hooks:
|
|
278
281
|
|
|
282
|
+
FizzyX follows the current official [shadcn installation and framework templates](https://ui.shadcn.com/docs/installation).
|
|
283
|
+
|
|
279
284
|
Prerequisites are Bun, Git, and network access to the framework and shadcn registries. pnpm is
|
|
280
285
|
only needed for the guarded compatibility fallback.
|
|
281
286
|
|
|
@@ -294,9 +299,24 @@ fizzyx openapi admin -i https://api.example.com/openapi.json -o ./admin --framew
|
|
|
294
299
|
```
|
|
295
300
|
|
|
296
301
|
Use `--framework tanstack-start` for TanStack Start, or add `--dry-run` to inspect the
|
|
297
|
-
scaffold commands without creating files. The
|
|
298
|
-
|
|
299
|
-
|
|
302
|
+
scaffold commands without creating files. The current `shadcn@latest init` owns the complete
|
|
303
|
+
Next.js or TanStack Start initialization; FizzyX no longer maintains a parallel framework scaffold
|
|
304
|
+
or `components.json` bootstrap. It uses Bun and `bunx` by default and only falls back to pnpm for a
|
|
305
|
+
known Bun compatibility failure. It never invokes npm or npx.
|
|
306
|
+
|
|
307
|
+
Forward new non-structural shadcn initializer options without waiting for FizzyX to model them by
|
|
308
|
+
repeating `--shadcn-arg`. Each occurrence is one exact argv value:
|
|
309
|
+
|
|
310
|
+
```sh
|
|
311
|
+
fizzyx openapi admin \
|
|
312
|
+
-i ./openapi.json -o ./pet-admin --framework nextjs \
|
|
313
|
+
--shadcn-arg=--rtl \
|
|
314
|
+
--shadcn-arg=--base --shadcn-arg=aria
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
FizzyX owns `--template`, `--name`, `--cwd`, and non-interactive flags, so forwarding them fails
|
|
318
|
+
before creating files. Monorepo layout is rejected for now because generated routes target the
|
|
319
|
+
project root. A forwarded `--preset` is allowed and becomes the preset recorded by the manifest.
|
|
300
320
|
|
|
301
321
|
Generated admin projects include:
|
|
302
322
|
|
|
@@ -311,6 +331,8 @@ Generated admin projects include:
|
|
|
311
331
|
- OXC `fmt`, `lint`, `lint:fix`, and `check` scripts, run automatically after first generation
|
|
312
332
|
- optional server-cookie authentication with a login page, server guard, logout, and same-origin BFF
|
|
313
333
|
- `.fizzyx/admin-manifest.json` regeneration safety that preserves user-edited generated files
|
|
334
|
+
- `.fizzyx/admin-ui.yaml`, a validated seed-once UI overlay for labels, sidebar grouping/order,
|
|
335
|
+
controlled icons, surfaces, and ordered field subsets
|
|
314
336
|
- project-local AI skills for auth discovery and conflict-safe generated-project development
|
|
315
337
|
|
|
316
338
|
The command works without `.fizzyx.yaml` when all three flags are provided. Teams may keep defaults
|
|
@@ -361,16 +383,18 @@ under `openapi.admin.auth` (`login_operation_id`, `access_token_path`, and so on
|
|
|
361
383
|
go through `/api/admin`. If auth is not configured, the existing public
|
|
362
384
|
`NEXT_PUBLIC_API_BASE_URL`/`VITE_API_BASE_URL` hook remains available.
|
|
363
385
|
|
|
364
|
-
The
|
|
386
|
+
The project-specific generated structure is below. Current shadcn Next.js templates place these
|
|
387
|
+
directories at the project root; TanStack Start places them under `src/`:
|
|
365
388
|
|
|
366
389
|
```text
|
|
367
|
-
src/
|
|
390
|
+
[src/]
|
|
368
391
|
components/admin/ # shell, DataTable, DynamicForm, query provider
|
|
369
392
|
lib/api/generated/ # fetch runtime, types, endpoints, query hooks
|
|
370
393
|
lib/api/admin-api.ts # environment and runtime API configuration
|
|
371
|
-
app/(admin)/ # Next.js routes (Next.js target)
|
|
372
|
-
routes/_admin/ # file routes (TanStack Start target)
|
|
394
|
+
app/(admin)/ # Next.js root routes (Next.js target; no src/ prefix)
|
|
395
|
+
routes/_admin/ # src/ file routes (TanStack Start target)
|
|
373
396
|
.fizzyx/admin-manifest.json
|
|
397
|
+
.fizzyx/admin-ui.yaml # user/agent-owned presentation overlay
|
|
374
398
|
.agents/skills/ # generated-project development and auth discovery guidance
|
|
375
399
|
```
|
|
376
400
|
|
|
@@ -379,6 +403,21 @@ unchanged generated files; local edits are reported and preserved as conflicts.
|
|
|
379
403
|
manifest are generator-owned. Prefer new wrapper/adapter/route files for durable customization; edit
|
|
380
404
|
the OpenAPI or auth configuration and regenerate for contract changes.
|
|
381
405
|
|
|
406
|
+
For presentation customization, edit `.fizzyx/admin-ui.yaml` directly or let an AI coding agent do
|
|
407
|
+
so. The overlay accepts only validated presentation fields and controlled icon names; it cannot add
|
|
408
|
+
API operations, imports, packages, URLs, or commands. Explicit `x-fizzyx-admin` metadata takes
|
|
409
|
+
precedence, then the overlay, then inferred defaults. Preview and apply changes with:
|
|
410
|
+
|
|
411
|
+
```sh
|
|
412
|
+
fizzyx openapi admin sync --plan
|
|
413
|
+
fizzyx openapi admin sync --apply
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
The plan reports semantic navigation/resource changes. The JSON manifest is machine-owned and must
|
|
417
|
+
not be edited by people or agents; applied OpenAPI and overlay fingerprints advance only after
|
|
418
|
+
conflict and quality checks pass. Existing projects with an older manifest remain syncable and are
|
|
419
|
+
not re-initialized.
|
|
420
|
+
|
|
382
421
|
Resource inference intentionally targets tagged, conventional collection/member CRUD paths.
|
|
383
422
|
Unmapped operations remain callable through the generated client and are reported as diagnostics.
|
|
384
423
|
List parameter inference recognizes common page/offset/limit/search/sort names; custom envelopes,
|
|
@@ -400,13 +439,13 @@ configure({ baseUrl: "https://api.example.com", storageKey: "myapp_token" });
|
|
|
400
439
|
|
|
401
440
|
// Or with custom logger + hooks
|
|
402
441
|
configure({
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
442
|
+
baseUrl: "https://api.example.com",
|
|
443
|
+
storageKey: "tb_token",
|
|
444
|
+
logger: { error: myReporter, warn: () => {}, info: () => {}, debug: () => {} },
|
|
445
|
+
hooks: [
|
|
446
|
+
{ onError: (ctx) => wx.showToast({ title: ctx.message }) },
|
|
447
|
+
{ onSuccess: (ctx) => reportAnalytics(ctx) },
|
|
448
|
+
],
|
|
410
449
|
});
|
|
411
450
|
|
|
412
451
|
// Token auto-loads from storage. Explicit load if needed:
|
|
@@ -506,3 +545,13 @@ Credentials are resolved in this priority order:
|
|
|
506
545
|
3. `.fizzyx.yaml` `access_key_id` / `secret_access_key` fields (legacy, discouraged)
|
|
507
546
|
|
|
508
547
|
Credentials stored as `default` (without `--env`) are used as a fallback for all environments when no env-specific key is found. This means you only need to run `fizzyx oss setup` once — dev, prod, and any other env will reuse the same keys.
|
|
548
|
+
|
|
549
|
+
## License
|
|
550
|
+
|
|
551
|
+
MIT, © 2026 Puffin Studio. See [`LICENSE`](LICENSE).
|
|
552
|
+
|
|
553
|
+
Some bundled skills are derived from [mattpocock/skills](https://github.com/mattpocock/skills)
|
|
554
|
+
(MIT, © 2026 Matt Pocock), rewritten in this project's voice and re-pointed at
|
|
555
|
+
`fizzyx` commands. They are listed file by file, with the upstream licence text,
|
|
556
|
+
in [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md) — which also flags three
|
|
557
|
+
skills whose origin is not established.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# Third-party notices
|
|
2
|
+
|
|
3
|
+
This package's own code is MIT, © 2026 Puffin Studio (see [`LICENSE`](LICENSE)).
|
|
4
|
+
Some of the bundled skills are not its own work. They are listed here with what
|
|
5
|
+
is known about where they came from and under what terms.
|
|
6
|
+
|
|
7
|
+
The skill markdown is inlined into `dist/main.js` at build time, so a published
|
|
8
|
+
`@puffinstudio/fizzyx` carries this content — which is why this file ships with
|
|
9
|
+
the package rather than only living in the repository.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## mattpocock/skills — MIT, © 2026 Matt Pocock
|
|
14
|
+
|
|
15
|
+
<https://github.com/mattpocock/skills>
|
|
16
|
+
|
|
17
|
+
The skills below are derived from that repository. Most have been rewritten in
|
|
18
|
+
this project's own voice and re-pointed at `fizzyx flow` / `fizzyx dev` commands
|
|
19
|
+
in place of upstream's tracker-specific instructions, and several accompanying
|
|
20
|
+
reference files were condensed. They remain derivative works.
|
|
21
|
+
|
|
22
|
+
| Bundled file | Upstream source |
|
|
23
|
+
| --------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
24
|
+
| `code-review.md` | `skills/engineering/code-review/SKILL.md` |
|
|
25
|
+
| `domain-modeling.md` | `skills/engineering/domain-modeling/SKILL.md` |
|
|
26
|
+
| `handoff.md` | `skills/productivity/handoff/SKILL.md` |
|
|
27
|
+
| `improve-codebase.md` | `skills/engineering/improve-codebase-architecture/SKILL.md` |
|
|
28
|
+
| `prototype.md` | `skills/engineering/prototype/SKILL.md` |
|
|
29
|
+
| `research.md` | `skills/engineering/research/SKILL.md` |
|
|
30
|
+
| `to-issues.md` | `skills/engineering/to-tickets/SKILL.md` (upstream renamed from `to-issues`) |
|
|
31
|
+
| `to-prd.md` | `skills/engineering/to-spec/SKILL.md` (upstream renamed from `to-prd`) |
|
|
32
|
+
| `triage.md` | `skills/engineering/triage/SKILL.md` |
|
|
33
|
+
| `resources/domain-modeling/ADR-FORMAT.md` | `skills/engineering/domain-modeling/ADR-FORMAT.md` |
|
|
34
|
+
| `resources/domain-modeling/CONTEXT-FORMAT.md` | `skills/engineering/domain-modeling/CONTEXT-FORMAT.md` |
|
|
35
|
+
| `resources/improve-codebase/HTML-REPORT.md` | `skills/engineering/improve-codebase-architecture/HTML-REPORT.md` |
|
|
36
|
+
| `resources/prototype/LOGIC.md` | `skills/engineering/prototype/LOGIC.md` |
|
|
37
|
+
| `resources/prototype/UI.md` | `skills/engineering/prototype/UI.md` |
|
|
38
|
+
| `resources/triage/AGENT-BRIEF.md` | `skills/engineering/triage/AGENT-BRIEF.md` |
|
|
39
|
+
| `resources/triage/OUT-OF-SCOPE.md` | `skills/engineering/triage/OUT-OF-SCOPE.md` |
|
|
40
|
+
|
|
41
|
+
Paths are relative to `src/skills/bundled/` here and to the upstream repository
|
|
42
|
+
root there. Content was last checked against `mattpocock/skills@66898f6`
|
|
43
|
+
(2026-07-13); see `src/use-cases/skill-service.ts`.
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
MIT License
|
|
47
|
+
|
|
48
|
+
Copyright (c) 2026 Matt Pocock
|
|
49
|
+
|
|
50
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
51
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
52
|
+
in the Software without restriction, including without limitation the rights
|
|
53
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
54
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
55
|
+
furnished to do so, subject to the following conditions:
|
|
56
|
+
|
|
57
|
+
The above copyright notice and this permission notice shall be included in all
|
|
58
|
+
copies or substantial portions of the Software.
|
|
59
|
+
|
|
60
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
61
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
62
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
63
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
64
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
65
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE OTHER DEALINGS IN THE
|
|
66
|
+
SOFTWARE.
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Origin not established
|
|
72
|
+
|
|
73
|
+
These three are **not** from `mattpocock/skills`, despite a commit message in
|
|
74
|
+
this repository's history saying otherwise. Their content does not appear
|
|
75
|
+
anywhere in that repository's full history:
|
|
76
|
+
|
|
77
|
+
| Bundled file | Distinguishing content | Searched for |
|
|
78
|
+
| -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------- |
|
|
79
|
+
| `codebase-design.md` | "Pass 1: Explore" through "Pass 5: Implement" | `Pass 1: Explore` — no match |
|
|
80
|
+
| `tdd.md` | "Phase 1: Triangulation", red/green/refactor | `Triangulation` — no match |
|
|
81
|
+
| `diagnosing-bugs.md` | OBSERVATION / CONTRACTION / HYPOTHESIS / EXPERIMENT / JUDGEMENT / RESOLUTION | `Socratic dialogue`, `CONTRACTION` — no match |
|
|
82
|
+
|
|
83
|
+
Upstream has skills by the same names, but with entirely different content.
|
|
84
|
+
Until the real source is identified these are listed as unknown rather than
|
|
85
|
+
credited to an author who may not have written them. If you recognise this
|
|
86
|
+
material, please open an issue.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## security-review.md
|
|
91
|
+
|
|
92
|
+
Carries `metadata.origin: ECC` in its own front matter. Terms not established
|
|
93
|
+
here.
|