@puffinstudio/fizzyx 1.2.1 → 1.3.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.
Files changed (3) hide show
  1. package/README.md +121 -2
  2. package/dist/main.js +2075 -464
  3. package/package.json +1 -1
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.
@@ -271,6 +272,124 @@ src/api/
271
272
  └── api.ts # tree-shakeable export functions + param types
272
273
  ```
273
274
 
275
+ ### Admin App
276
+
277
+ Generate a standalone shadcn admin project with a typed fetch client and TanStack Query hooks:
278
+
279
+ Prerequisites are Bun, Git, and network access to the framework and shadcn registries. pnpm is
280
+ only needed for the guarded compatibility fallback.
281
+
282
+ ```sh
283
+ fizzyx openapi admin \
284
+ --input ./openapi.json \
285
+ --output ./pet-admin \
286
+ --framework nextjs \
287
+ --create-mode dialog
288
+ ```
289
+
290
+ URLs work as input too:
291
+
292
+ ```sh
293
+ fizzyx openapi admin -i https://api.example.com/openapi.json -o ./admin --framework tanstack-start
294
+ ```
295
+
296
+ 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.
300
+
301
+ Generated admin projects include:
302
+
303
+ - shadcn components installed with `shadcn add --all`
304
+ - a Base UI Mira admin preset with persistent system/light/dark themes and a header toggle
305
+ - declarative TanStack Table list pages whose search, typed filters, pagination, and sorting come
306
+ only from query capabilities declared by the list operation
307
+ - operation-level Zod v4 schemas rendered by AutoForm's TanStack Form adapter and editable shadcn
308
+ source components, including enum selects, booleans, dates, numbers, arrays, and nested objects
309
+ - consistent `page` or `dialog` create/edit presentation with generated validation messages
310
+ - detail routes, reusable inline delete confirmation, and a typed fetch + TanStack Query client
311
+ - OXC `fmt`, `lint`, `lint:fix`, and `check` scripts, run automatically after first generation
312
+ - optional server-cookie authentication with a login page, server guard, logout, and same-origin BFF
313
+ - `.fizzyx/admin-manifest.json` regeneration safety that preserves user-edited generated files
314
+ - project-local AI skills for auth discovery and conflict-safe generated-project development
315
+
316
+ The command works without `.fizzyx.yaml` when all three flags are provided. Teams may keep defaults
317
+ in the optional project config; explicit flags fill or override those values:
318
+
319
+ ```yaml
320
+ openapi:
321
+ admin:
322
+ input: ./openapi.yaml
323
+ output: ./apps/admin
324
+ framework: nextjs
325
+ preset: b1tNoIJIf # optional shadcn preset override
326
+ create_mode: page # create and edit both use page or dialog presentation
327
+ ```
328
+
329
+ On first generation, the precedence is `--preset`/`--create-mode`, then `openapi.admin` project
330
+ defaults, then the FizzyX defaults (`b1tNoIJIf` and `page`). Presets customize the shadcn style,
331
+ colors, font, radius, charts, and menu treatment; the generated theme provider always keeps light
332
+ and dark mode available. Regeneration may safely switch `create_mode`; create and edit switch
333
+ together so one resource does not mix interaction patterns. It preserves the recorded
334
+ preset and rejects replacing it in place because shadcn component files may contain user changes;
335
+ use a new output or review an explicit `shadcn apply` diff instead.
336
+
337
+ Authentication is never enabled from endpoint names alone. Without an explicit contract, FizzyX
338
+ reports ranked login/logout/me/refresh candidates and tells the user what must be confirmed. Put the
339
+ durable API semantics in the OpenAPI document (preferred):
340
+
341
+ ```yaml
342
+ x-fizzyx-admin:
343
+ auth:
344
+ mode: server-cookie
345
+ loginOperationId: authLogin
346
+ logoutOperationId: authLogout
347
+ meOperationId: usersMe
348
+ usernameField: email # optional when inferable from the login request schema
349
+ passwordField: password # optional when inferable
350
+ accessTokenPath: data.access_token
351
+ refreshTokenPath: data.refresh_token
352
+ routes:
353
+ login: /login
354
+ afterLogin: /users
355
+ ```
356
+
357
+ For a remote or immutable spec, the equivalent optional `.fizzyx.yaml` override uses snake-case keys
358
+ under `openapi.admin.auth` (`login_operation_id`, `access_token_path`, and so on). An OpenAPI
359
+ `x-fizzyx-admin.auth` block takes precedence when both exist. Server-cookie mode uses the server-only
360
+ `API_BASE_URL`; tokens stay in HttpOnly, Secure-in-production, SameSite cookies and browser API calls
361
+ go through `/api/admin`. If auth is not configured, the existing public
362
+ `NEXT_PUBLIC_API_BASE_URL`/`VITE_API_BASE_URL` hook remains available.
363
+
364
+ The main generated structure is:
365
+
366
+ ```text
367
+ src/
368
+ components/admin/ # shell, DataTable, DynamicForm, query provider
369
+ lib/api/generated/ # fetch runtime, types, endpoints, query hooks
370
+ 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)
373
+ .fizzyx/admin-manifest.json
374
+ .agents/skills/ # generated-project development and auth discovery guidance
375
+ ```
376
+
377
+ The output directory must be empty on the first run. Re-run the same command to update
378
+ unchanged generated files; local edits are reported and preserved as conflicts. Files listed in the
379
+ manifest are generator-owned. Prefer new wrapper/adapter/route files for durable customization; edit
380
+ the OpenAPI or auth configuration and regenerate for contract changes.
381
+
382
+ Resource inference intentionally targets tagged, conventional collection/member CRUD paths.
383
+ Unmapped operations remain callable through the generated client and are reported as diagnostics.
384
+ List parameter inference recognizes common page/offset/limit/search/sort names; custom envelopes,
385
+ ambiguous authorization contracts, relationships, file inputs, and router-only TanStack projects are
386
+ not inferred. `upstream-cookie` is parsed but remains disabled until an application-specific cookie
387
+ rewrite policy is supplied; `server-cookie` is the safe generated default.
388
+
389
+ For a complete local login + protected CRUD walkthrough, use
390
+ [`examples/openapi-admin-auth`](./examples/openapi-admin-auth/README.md). It includes an OpenAPI
391
+ document, a localhost-only Bun mock API, fixed demo credentials, and commands for both frameworks.
392
+
274
393
  ### Generated Runtime API
275
394
 
276
395
  ```ts