@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.
- package/README.md +53 -14
- package/dist/main.js +646 -602
- 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
|
|
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:
|