@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.
- package/README.md +121 -2
- package/dist/main.js +2075 -464
- 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
|