@puffinstudio/fizzyx 1.4.0 → 1.5.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 +37 -14
  2. package/dist/main.js +420 -385
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -15,9 +15,9 @@ bun add -g @puffinstudio/fizzyx
15
15
  Use `.fizzyx.yaml` as the project config file for board and workflow settings.
16
16
 
17
17
  ```sh
18
- fizzyx flow work
19
- fizzyx flow list [--indexed-by <lane>] [--search <terms>] [--json]
20
- fizzyx flow search "<query>" [--all-boards] [--json]
18
+ fizzyx flow work [--agent]
19
+ fizzyx flow list [--indexed-by <lane>] [--search <terms>] [--json [--full]]
20
+ fizzyx flow search "<query>" [--all-boards] [--json [--full]]
21
21
  fizzyx flow columns
22
22
  fizzyx flow create --draft
23
23
  fizzyx flow create "<title>" --desc <draft-path>
@@ -27,11 +27,11 @@ fizzyx flow edit <card> [--title "<title>"] [--desc <file|->]
27
27
  fizzyx flow assign <card> <user>
28
28
  fizzyx flow comment <card> "<single-line body>"
29
29
  fizzyx flow comment <card> --body-file <markdown-file|->
30
- fizzyx flow show <card>
30
+ fizzyx flow show <card> [--check <n> | --uncheck <n>] [--json [--full]]
31
31
  fizzyx flow move <card> <column-id-or-name>
32
32
  fizzyx flow start <card>
33
33
  fizzyx flow review <card>
34
- fizzyx flow done <card> "commit <sha>: <subject>"
34
+ fizzyx flow done <card> ["<closing note>"] [--complete-steps]
35
35
  fizzyx flow reopen <card>
36
36
  fizzyx flow block <card> "<reason>"
37
37
  fizzyx flow unblock <card> "<reason>"
@@ -40,7 +40,9 @@ fizzyx flow doctor
40
40
  fizzyx flow repair
41
41
  ```
42
42
 
43
- `flow done` requires all steps to be complete and closes the card into Done.
43
+ `flow done` requires all steps to be complete (or `--complete-steps`) and closes the card. It needs no commit or branch reference and never reads git; the optional second argument is a free-text note recorded as a `done:` comment.
44
+ `flow work --agent` prints at most eight lines: your in-progress cards with their step progress and next unchecked step, then the next card.
45
+ `flow edit` requires a `## Steps` list only for a card that already has steps; a document card without steps can be updated from any description.
44
46
  `flow create` expects the standard draft shape with a `## Steps` task list; generate it with `flow create --draft` instead of passing plain text.
45
47
  `flow create` does not assign by default. Use `--assign <user>` while creating or `flow assign <card> <user>` afterwards.
46
48
  Drafts are stored outside the worktree in Git-local state (or the user state directory outside a Git repository). `flow edit <card> --draft` rebuilds one from the remote card.
@@ -49,7 +51,9 @@ Drafts are stored outside the worktree in Git-local state (or the user state dir
49
51
  `flow move` also accepts the Fizzy system targets `maybe`/`triage` and `not-now`; closing remains guarded by `flow done`.
50
52
  `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.
51
53
  `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.
52
- High-frequency flow commands accept `--json` and return an `ok`/`data`/`summary` envelope with next-action breadcrumbs for agents.
54
+ Flow commands print compact text by default, which is the cheapest form for an agent to read. High-frequency commands also accept `--json` and return a single-line `ok`/`data`/`summary` envelope with next-action breadcrumbs. Card lists in JSON are lean (`number`, `title`, `column`, `assignees`, `steps: { done, total }`) and `flow show --json` carries the description once; add `--full` for every field.
55
+ Set `flow.card.language: zh-CN` in `.fizzyx.yaml` to have the built-in card template and the generated `AGENTS.md` instruction ask for card content in Simplified Chinese (default `en`). Headings such as `## Steps` stay English, CLI output is unaffected, and a project-local `.agents/skills/fizzyx/CARD_TEMPLATE.md` still wins.
56
+ `flow.wip_limit` (default 20) caps the in-progress cards of the token's user on the board.
53
57
  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.
54
58
  `flow improve` is retained as a deprecated compatibility alias; use `fizzyx skill run improve-codebase` for the actual codebase workflow.
55
59
 
@@ -60,14 +64,12 @@ project instructions are preserved, and repeated initialization does not duplica
60
64
  Agent loop for card-backed code work:
61
65
 
62
66
  ```sh
63
- fizzyx flow work
67
+ fizzyx flow work --agent # what is in progress, what is next
64
68
  fizzyx flow show <card>
65
- fizzyx dev status --agent
66
- fizzyx dev start <slug> --kind <feature|fix|hotfix|ops|chore|docs> --card <card>
67
69
  fizzyx flow start <card>
68
- fizzyx dev ready --agent
69
- fizzyx flow review <card>
70
- fizzyx flow done <card> "commit <sha>: <subject>"
70
+ fizzyx dev start <slug> --kind <feature|fix|hotfix|ops|chore|docs> --worktree --agent # one worktree per sub-task; cd to worktree_path
71
+ fizzyx flow show <card> --check <n> # tick a step once its work is on the base branch
72
+ fizzyx flow done <card>
71
73
  ```
72
74
 
73
75
  Use `fizzyx skill ...` for bundled skills and project pins. Use flow commands for repair and health checks.
@@ -88,9 +90,14 @@ fizzyx dev baseline <show|accept>
88
90
  fizzyx dev ready [--agent] [--full]
89
91
  fizzyx dev promote <source> --to <environment|main> --dry-run
90
92
  fizzyx dev cleanup [--confirm-delete]
91
- fizzyx dev doctor
93
+ fizzyx dev doctor [--agent] [--verbose]
92
94
  ```
93
95
 
96
+ `dev start --worktree` creates the branch in `.git/fizzyx/worktrees/<branch>` and works from a checkout with uncommitted changes, which it never touches.
97
+ `dev doctor` prints section counts and names only the branches holding commits that are on no remote and not on the base (`local_only`); `--verbose` lists every section. It recognises branches whose commits were cherry-picked onto the base as integrated.
98
+ `dev cleanup` previews exactly which branches `--confirm-delete` would remove and why. Only work-role branches (built-in prefixes or `dev.branch_prefixes`) are deleted; a cherry-picked branch is pinned at `refs/fizzyx/deleted/<branch>` first and can be restored with `git branch <branch> refs/fizzyx/deleted/<branch>`.
99
+ `dev ready` prints `checks: none configured` when the project sets no `dev.checks.ready`, because it then verifies branch state only.
100
+
94
101
  Branch/card associations live in local Git config. Unchanged pre-existing worktree files may be accepted with `dev baseline accept`; readiness receipts are stored under `.git/fizzyx/` and are invalidated when HEAD changes. `.fizzyx.yaml` remains shared project policy only.
95
102
 
96
103
  Production promotions stay guarded:
@@ -461,6 +468,22 @@ setToken(null); // logout, clears storage
461
468
  - `Logger` controls **output** (console, file, sentry). Default: `console.error/warn/info/debug` with `[fizzyx]` prefix.
462
469
  - `RequestHook` fires **business callbacks** at lifecycle points (`onRequest`, `onSuccess`, `onError`). Use for toast, analytics, loading state.
463
470
 
471
+ Applications that already own an isolated session can supply a JSON `transport` instead of
472
+ using the generated native request and token storage:
473
+
474
+ ```ts
475
+ configure({
476
+ transport: (method, path, options) => session.request(method, path, options),
477
+ responseExtractor: (value) => value,
478
+ });
479
+ ```
480
+
481
+ The transport receives the generated endpoint path, query, body and headers. It owns
482
+ origin validation, authentication, logging, lifecycle hooks and errors. Transport failures
483
+ are preserved rather than converted into generated native-request errors. The response
484
+ extractor still runs on successful results; choose the identity extractor for APIs without
485
+ an envelope. Upload and download retain their separate native implementations.
486
+
464
487
  ### Generated Endpoint API
465
488
 
466
489
  Each endpoint is a standalone export function with typed params: