@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.
- package/README.md +167 -9
- package/dist/main.js +2264 -609
- 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
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
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:
|