@puffinstudio/fizzyx 1.2.1 → 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 +167 -9
  2. package/dist/main.js +2264 -609
  3. package/package.json +80 -80
package/README.md CHANGED
@@ -25,7 +25,8 @@ fizzyx flow create "<title>" --assign <user> --desc <draft-path>
25
25
  fizzyx flow edit <card> --draft
26
26
  fizzyx flow edit <card> [--title "<title>"] [--desc <file|->]
27
27
  fizzyx flow assign <card> <user>
28
- fizzyx flow comment <card> "<body>"
28
+ fizzyx flow comment <card> "<single-line body>"
29
+ fizzyx flow comment <card> --body-file <markdown-file|->
29
30
  fizzyx flow show <card>
30
31
  fizzyx flow move <card> <column-id-or-name>
31
32
  fizzyx flow start <card>
@@ -46,7 +47,7 @@ Drafts are stored outside the worktree in Git-local state (or the user state dir
46
47
  `flow edit` updates the title, description, or both. Description input accepts a standard card draft file or `-` for stdin and synchronizes its `## Steps` task list.
47
48
  `flow columns` lists the real columns and IDs on the configured board. `flow move` is the column-agnostic primitive for custom Fizzy boards. `flow start` uses the configured `in_progress` column; `flow review` is a convenience command for the built-in REVIEW preset.
48
49
  `flow move` also accepts the Fizzy system targets `maybe`/`triage` and `not-now`; closing remains guarded by `flow done`.
49
- `flow list` filters cards on the configured board, while `flow search` uses Fizzy full-text search and filters results back to the project board unless `--all-boards` is passed. `flow comment` records a standardized note.
50
+ `flow list` filters cards on the configured board, while `flow search` uses Fizzy full-text search and filters results back to the project board unless `--all-boards` is passed. `flow comment` records a standardized note and renders safe Markdown as Fizzy rich text; use `--body-file -` for multiline stdin.
50
51
  `flow reopen`, `flow unblock`, and `flow untriage` provide the inverse lifecycle actions. Unblock returns the card to the configured default column; untriage returns it to Fizzy's system Maybe state.
51
52
  High-frequency flow commands accept `--json` and return an `ok`/`data`/`summary` envelope with next-action breadcrumbs for agents.
52
53
  Normal flow commands never create or rename board columns. When `flow:` is missing, explicit `fizzyx init` installs the bundled preset; custom boards can map their existing default and in-progress column IDs in `.fizzyx.yaml` and use `flow move` for all other transitions.
@@ -262,6 +263,9 @@ Options:
262
263
 
263
264
  If `--input`/`--output`/`--client` are omitted, values from `.fizzyx.yaml` `openapi[0]` are used.
264
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
+
265
269
  Output is 3 files — runtime, types, and tree-shakeable endpoint functions:
266
270
 
267
271
  ```
@@ -271,6 +275,160 @@ src/api/
271
275
  └── api.ts # tree-shakeable export functions + param types
272
276
  ```
273
277
 
278
+ ### Admin App
279
+
280
+ Generate a standalone shadcn admin project with a typed fetch client and TanStack Query hooks:
281
+
282
+ FizzyX follows the current official [shadcn installation and framework templates](https://ui.shadcn.com/docs/installation).
283
+
284
+ Prerequisites are Bun, Git, and network access to the framework and shadcn registries. pnpm is
285
+ only needed for the guarded compatibility fallback.
286
+
287
+ ```sh
288
+ fizzyx openapi admin \
289
+ --input ./openapi.json \
290
+ --output ./pet-admin \
291
+ --framework nextjs \
292
+ --create-mode dialog
293
+ ```
294
+
295
+ URLs work as input too:
296
+
297
+ ```sh
298
+ fizzyx openapi admin -i https://api.example.com/openapi.json -o ./admin --framework tanstack-start
299
+ ```
300
+
301
+ Use `--framework tanstack-start` for TanStack Start, or add `--dry-run` to inspect the
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.
320
+
321
+ Generated admin projects include:
322
+
323
+ - shadcn components installed with `shadcn add --all`
324
+ - a Base UI Mira admin preset with persistent system/light/dark themes and a header toggle
325
+ - declarative TanStack Table list pages whose search, typed filters, pagination, and sorting come
326
+ only from query capabilities declared by the list operation
327
+ - operation-level Zod v4 schemas rendered by AutoForm's TanStack Form adapter and editable shadcn
328
+ source components, including enum selects, booleans, dates, numbers, arrays, and nested objects
329
+ - consistent `page` or `dialog` create/edit presentation with generated validation messages
330
+ - detail routes, reusable inline delete confirmation, and a typed fetch + TanStack Query client
331
+ - OXC `fmt`, `lint`, `lint:fix`, and `check` scripts, run automatically after first generation
332
+ - optional server-cookie authentication with a login page, server guard, logout, and same-origin BFF
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
336
+ - project-local AI skills for auth discovery and conflict-safe generated-project development
337
+
338
+ The command works without `.fizzyx.yaml` when all three flags are provided. Teams may keep defaults
339
+ in the optional project config; explicit flags fill or override those values:
340
+
341
+ ```yaml
342
+ openapi:
343
+ admin:
344
+ input: ./openapi.yaml
345
+ output: ./apps/admin
346
+ framework: nextjs
347
+ preset: b1tNoIJIf # optional shadcn preset override
348
+ create_mode: page # create and edit both use page or dialog presentation
349
+ ```
350
+
351
+ On first generation, the precedence is `--preset`/`--create-mode`, then `openapi.admin` project
352
+ defaults, then the FizzyX defaults (`b1tNoIJIf` and `page`). Presets customize the shadcn style,
353
+ colors, font, radius, charts, and menu treatment; the generated theme provider always keeps light
354
+ and dark mode available. Regeneration may safely switch `create_mode`; create and edit switch
355
+ together so one resource does not mix interaction patterns. It preserves the recorded
356
+ preset and rejects replacing it in place because shadcn component files may contain user changes;
357
+ use a new output or review an explicit `shadcn apply` diff instead.
358
+
359
+ Authentication is never enabled from endpoint names alone. Without an explicit contract, FizzyX
360
+ reports ranked login/logout/me/refresh candidates and tells the user what must be confirmed. Put the
361
+ durable API semantics in the OpenAPI document (preferred):
362
+
363
+ ```yaml
364
+ x-fizzyx-admin:
365
+ auth:
366
+ mode: server-cookie
367
+ loginOperationId: authLogin
368
+ logoutOperationId: authLogout
369
+ meOperationId: usersMe
370
+ usernameField: email # optional when inferable from the login request schema
371
+ passwordField: password # optional when inferable
372
+ accessTokenPath: data.access_token
373
+ refreshTokenPath: data.refresh_token
374
+ routes:
375
+ login: /login
376
+ afterLogin: /users
377
+ ```
378
+
379
+ For a remote or immutable spec, the equivalent optional `.fizzyx.yaml` override uses snake-case keys
380
+ under `openapi.admin.auth` (`login_operation_id`, `access_token_path`, and so on). An OpenAPI
381
+ `x-fizzyx-admin.auth` block takes precedence when both exist. Server-cookie mode uses the server-only
382
+ `API_BASE_URL`; tokens stay in HttpOnly, Secure-in-production, SameSite cookies and browser API calls
383
+ go through `/api/admin`. If auth is not configured, the existing public
384
+ `NEXT_PUBLIC_API_BASE_URL`/`VITE_API_BASE_URL` hook remains available.
385
+
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/`:
388
+
389
+ ```text
390
+ [src/]
391
+ components/admin/ # shell, DataTable, DynamicForm, query provider
392
+ lib/api/generated/ # fetch runtime, types, endpoints, query hooks
393
+ lib/api/admin-api.ts # environment and runtime API configuration
394
+ app/(admin)/ # Next.js root routes (Next.js target; no src/ prefix)
395
+ routes/_admin/ # src/ file routes (TanStack Start target)
396
+ .fizzyx/admin-manifest.json
397
+ .fizzyx/admin-ui.yaml # user/agent-owned presentation overlay
398
+ .agents/skills/ # generated-project development and auth discovery guidance
399
+ ```
400
+
401
+ The output directory must be empty on the first run. Re-run the same command to update
402
+ unchanged generated files; local edits are reported and preserved as conflicts. Files listed in the
403
+ manifest are generator-owned. Prefer new wrapper/adapter/route files for durable customization; edit
404
+ the OpenAPI or auth configuration and regenerate for contract changes.
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
+
421
+ Resource inference intentionally targets tagged, conventional collection/member CRUD paths.
422
+ Unmapped operations remain callable through the generated client and are reported as diagnostics.
423
+ List parameter inference recognizes common page/offset/limit/search/sort names; custom envelopes,
424
+ ambiguous authorization contracts, relationships, file inputs, and router-only TanStack projects are
425
+ not inferred. `upstream-cookie` is parsed but remains disabled until an application-specific cookie
426
+ rewrite policy is supplied; `server-cookie` is the safe generated default.
427
+
428
+ For a complete local login + protected CRUD walkthrough, use
429
+ [`examples/openapi-admin-auth`](./examples/openapi-admin-auth/README.md). It includes an OpenAPI
430
+ document, a localhost-only Bun mock API, fixed demo credentials, and commands for both frameworks.
431
+
274
432
  ### Generated Runtime API
275
433
 
276
434
  ```ts
@@ -281,13 +439,13 @@ configure({ baseUrl: "https://api.example.com", storageKey: "myapp_token" });
281
439
 
282
440
  // Or with custom logger + hooks
283
441
  configure({
284
- baseUrl: "https://api.example.com",
285
- storageKey: "tb_token",
286
- logger: { error: myReporter, warn: () => {}, info: () => {}, debug: () => {} },
287
- hooks: [
288
- { onError: (ctx) => wx.showToast({ title: ctx.message }) },
289
- { onSuccess: (ctx) => reportAnalytics(ctx) },
290
- ],
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
+ ],
291
449
  });
292
450
 
293
451
  // Token auto-loads from storage. Explicit load if needed: