@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 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 generator uses the official framework
298
- scaffolds, Bun and `bunx` by default, and only falls back to pnpm for a known Bun
299
- compatibility failure. It never invokes npm or npx.
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 main generated structure is:
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
- baseUrl: "https://api.example.com",
404
- storageKey: "tb_token",
405
- logger: { error: myReporter, warn: () => {}, info: () => {}, debug: () => {} },
406
- hooks: [
407
- { onError: (ctx) => wx.showToast({ title: ctx.message }) },
408
- { onSuccess: (ctx) => reportAnalytics(ctx) },
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.