@puffinstudio/fizzyx 1.3.0 → 1.3.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 (3) hide show
  1. package/README.md +53 -14
  2. package/dist/main.js +646 -602
  3. package/package.json +80 -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 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: