@staff0rd/assist 0.684.0 → 0.685.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 CHANGED
@@ -59,6 +59,7 @@ After installation, the `assist` command will be available globally. You can als
59
59
  - `/refactor` - Run refactoring checks for code quality
60
60
  - `/prompts` - Analyze denied tool calls and suggest settings changes to auto-allow recurring prompts
61
61
  - `/recall` - Recall the most recent handover note for this repo
62
+ - `/releases-configure` - Set this repo's release promotion topology: read its workflow files, follow every `uses:` reusable-workflow call to whatever depth it nests, flatten the `needs:` graph across those boundaries into nodes and edges, put the graph to the user to accept or edit, then write it with `assist releases configure --streams ...` to the project `assist.yml` or this repo's block in `~/.assist.yml`. The repo is the one you are in — it is never passed
62
63
  - `/refine` - Refine an existing backlog item through conversation
63
64
  - `/rename [title]` - Retitle this session's dashboard card via `assist sessions rename`; uses the argument verbatim, or infers a short title from the conversation when given none
64
65
  - `/restructure` - Analyze and restructure tightly-coupled files
@@ -160,7 +161,7 @@ Every command supports `--help` for full detail on its flags and behaviour.
160
161
  - `assist github issue fix-structure <target> [-R <owner>/<repo>] [--level <level>] [--type-chain <names>] [--strip-label <label>...] [--apply]` - Normalise the issue types across one issue subtree, reading and writing nothing outside it. `<target>` is `owner/repo#number`, a github.com issue URL, or a bare number with `-R`; a bare number with no repo is refused rather than guessed. Walks the subtree via sub-issues level by level (a single deep query blows the GraphQL node limit) and reports the type each issue should carry: every level below the target is typed to the next level down the chain, matching type names loosely so `Subtask` and `Sub-task` both bind to the leaf. The chain defaults to `Epic` > `Story` > `Subtask`; `--type-chain Initiative,Feature,Task` replaces it, parent level first, and every level named must already exist as an issue type on the organisation or the run fails listing the ones that do. Untyped issues are typed rather than skipped, and cross-repo children are handled in the one run. The target's own level is inferred from its issue type, so aiming at a story types its children as subtasks; when its type is not in the chain the level cannot be inferred and the command exits non-zero naming the type it has. `--level` asserts the position instead, which also types the target itself. No label is touched unless `--strip-label` names it; it is repeatable, matched case-insensitively, and each label is removed by the id found on that issue, since label ids differ per repository. Anything nested below the leaf level fails the run before a single write, naming the offender and its parent; nothing is ever re-parented. Without `--apply` nothing is written. `--apply` announces each write before it is issued and flushes it, so a long run shows progress, then re-walks the subtree and fails with a non-zero exit if any drift remains
161
162
  - `assist news add [url]` - Add an RSS feed URL (rendered in the sessions web News tab)
162
163
  - `assist releases [list]` - Print the declared release promotion streams — each stream's repo, release workflow, nodes and edges — as read from `releases.streams`. The same declaration drives the [Releases page](#releases) of the sessions dashboard
163
- - `assist releases configure <owner/repo>` - Derive that repo's promotion topology and write it to `releases.streams`. Launches a Claude session that reads the repo's workflow files from GitHub, follows every `uses:` reusable-workflow call to whatever depth it nests, flattens the `needs:` graph across those boundaries into nodes and edges, and confirms the graph with you before writing. On exit the command re-reads the config: a block that fails the schema is reported field by field and exits non-zero, and a valid one is printed back as the environments, steps and edges it derived for that repo. Streams declared for other repos are left alone
164
+ - `assist releases configure --streams <file> [--scope <project|repo>]` - Validate release streams and write them to `releases.streams`. `<file>` is a JSON or YAML array of streams (`-` reads stdin); a stream that names no `repo` gets the current one, so the caller never passes it. The array is checked twice before anything is written — every edge endpoint must be a declared node id and no two nodes may share one, then the whole config must pass the schema — and a failure prints each error and writes nothing. Streams already declared for other repos are kept, the ones for the repos in the file are replaced, and what was written is printed back as its environments, steps and edges. `--scope` picks the project `assist.yml` (default) or this repo's block in `~/.assist.yml`. The topology itself is derived by [`/releases-configure`](#claude-commands), which reads the repo's workflows and calls this
164
165
 
165
166
  ### Backlog
166
167
 
@@ -433,7 +434,14 @@ Requires `assist` installed on the Windows host.
433
434
 
434
435
  ### Releases
435
436
 
436
- The **Releases** tab draws one row per declared release stream: a left rail naming the stream, its repo and its release workflow, and beside it the stream's environments with what is live in each — the commit of its newest deployment whose status is `success`, how long ago that went live, and how many commits behind the repo's default branch it is. A deployment still `waiting` on an approval is gated, not live, so it is passed over. Every timestamp renders in the viewer's own timezone, and every glyph and short token carries a tooltip on hover and on keyboard focus. A stream whose repo cannot be read shows its error in place of its environments, leaving the other streams intact. Live state is read from the repo's GitHub deployments, so two streams deploying into the same environment read the same commit.
437
+ The **Releases** tab draws one row per declared release stream: a left rail naming the stream, its repo, its release workflow, the tip of the default branch, a link to the latest run and a summary pill per group of environments, and beside it the promotion graph the stream declares. Nodes sit in columns by edge depth, so a fan-in gate or a missing step is something you see rather than something you decode, and an SVG edge joins each pair — solid where the promotion has happened, dashed where the target does not carry the source's commit. Hovering or focusing a summary pill dims the graph and rings exactly the nodes that pill counts.
438
+
439
+ Two layers sit over the one graph, toggled rather than shown side by side:
440
+
441
+ - **What's live** — per environment, the commit of its newest deployment whose status is `success`, how long ago that went live, and how many commits behind the repo's default branch it is. A deployment still `waiting` on an approval is gated, not live, so it is passed over and shown on its own `queued` line instead.
442
+ - **Latest run** — per node, the state of its job in the latest run of the stream's workflow: how long it took, how long it has been sitting on an environment approval, or that the run never got there. Jobs are matched to nodes by name, most specific node first, so `Deploy to US UAT` goes to the `us-uat` node rather than the `uat` one.
443
+
444
+ Every timestamp renders in the viewer's own timezone, and every glyph and short token carries a tooltip on hover and on keyboard focus. Commit SHAs link to the commit, and their tooltip carries the commit subject and author. A stream whose repo or workflow cannot be read shows its error in place of its graph, leaving the other streams intact. Live state is read from the repo's GitHub deployments, so two streams deploying into the same environment read the same commit.
437
445
 
438
446
  Topology is declared, not derived: assist does not parse workflow YAML at runtime.
439
447
 
@@ -453,7 +461,7 @@ releases:
453
461
  ```
454
462
 
455
463
  - `id` names the node within the stream and is what `edges` refer to. A node with an `environment` is a GitHub deployment environment and reads live state; `kind` (`build` or `gate`) marks a node that deploys nothing. `label` overrides the text on the node, which is otherwise the `id`.
456
- - `assist releases configure <owner/repo>` derives the block for a repo instead of hand-writing it, and `assist releases list` prints whatever is declared back as assist reads it.
464
+ - `/releases-configure` derives the block from the repo's own workflows instead of hand-writing it, and `assist releases list` prints whatever is declared back as assist reads it.
457
465
 
458
466
  ## Parallel work
459
467
 
@@ -489,7 +497,7 @@ A restart kills every managed session's pty, which also kills any background tas
489
497
  - `commit.expectedBranch` — when set (e.g. `main`), `assist commit` prints a non-blocking warning if HEAD is on any other branch, so work on a stray branch isn't silently orphaned
490
498
  - `branch.prefix` — when set (e.g. `sw`), `assist branch <slug>` prepends `<prefix>/` to the branch name
491
499
  - `branch.defaultBranch` — override the base branch, which is otherwise resolved live from the remote (`git ls-remote --symref origin HEAD`), falling back to `main`
492
- - `releases.streams` — the release promotion streams drawn by the [Releases page](#releases), derived by `assist releases configure <owner/repo>` and printed by `assist releases list`
500
+ - `releases.streams` — the release promotion streams drawn by the [Releases page](#releases), derived by `/releases-configure`, written by `assist releases configure --streams` and printed by `assist releases list`
493
501
  - `cliHook.blockNpmRun` — when `true` (default), `assist cli-hook` denies `npm run` and redirects to `assist run <name>`, `assist verify` or `assist build`. Set it to `false` in a repo that genuinely needs npm scripts. `npm install`, `npm ci` and `npm test` are never affected
494
502
 
495
503
  ## Acceptance criteria outliner extension
@@ -0,0 +1,73 @@
1
+ ---
2
+ description: Derive this repo's release promotion topology from its workflows and write it to releases.streams
3
+ ---
4
+
5
+ The user wants `releases.streams` set for **this repo** — the promotion graph the [Releases page](#releases) draws. You derive it from the repo's own GitHub Actions workflows; the user accepts or edits it; `assist` validates and writes it.
6
+
7
+ The repo is the one you are in. Resolve it with `gh repo view --json nameWithOwner --jq .nameWithOwner` — never ask the user for it.
8
+
9
+ ## Step 1: Read what is already declared
10
+
11
+ ```
12
+ assist releases list
13
+ ```
14
+
15
+ A stream already declared for this repo is the starting point — propose a change to it only where you can say why.
16
+
17
+ ## Step 2: Read the workflows
18
+
19
+ Read them from the checkout you are in (`.github/workflows/`). Where a workflow lives in another repo, read it with `gh api repos/<owner>/<name>/contents/<path> --jq .content | base64 -d`.
20
+
21
+ A job with `uses: <owner>/<name>/.github/workflows/<file>@<ref>` calls a reusable workflow. Read that file too, from the repo and ref it names, and keep following `uses:` to whatever depth it nests — a deploy three levels down is still a node in the graph. Do not stop at the first level and do not guess what a reusable workflow does from its name.
22
+
23
+ ## Step 3: Derive the graph
24
+
25
+ - **Streams** — one per release pipeline. A repo releasing two apps has two streams, whether they share a workflow or not. Name each after the thing released, not after the workflow file. `workflow` is the file name of the top-level workflow the promotion runs under, not the reusable ones it calls.
26
+ - **Nodes** — one per step worth drawing:
27
+ - a job that deploys to a GitHub environment: `{ id: <short-id>, environment: <name> }`
28
+ - a job that builds or packages and deploys nothing: `{ id: <short-id>, kind: build }`
29
+ - a job or environment approval that only gates promotion: `{ id: <short-id>, kind: gate }`
30
+ - `label` overrides the text drawn on the node; set it only where `id` reads badly.
31
+ - **Environment names** must be the names GitHub knows, since live state is read from the repo's deployments against them. Where a reusable workflow takes the name as an input, follow the input back to its value at the call site rather than recording the input's name. Check every one against `gh api repos/<owner>/<name>/environments --jq '.environments[].name'`.
32
+ - **Edges** — `[from, to]` for each `needs:` relation between the nodes you kept, flattened across reusable-workflow boundaries: where a job needs a `uses:` job, the edge runs to or from the inner job that actually neighbours it. Fan-in (several nodes into one gate) and fan-out (one node into several) are both expected and must both survive the flattening.
33
+
34
+ ## Step 4: Put the graph to the user
35
+
36
+ Show the nodes and edges you intend to write, and say which workflow file each node came from — including the reusable ones, so the user can see the chain you followed. Ask them to accept or edit, and ask which config file it goes to:
37
+
38
+ - `project` — the repo's own `assist.yml`, checked in, so the team sees the same graph
39
+ - `repo` — this repo's block in `~/.assist.yml`, personal to this machine
40
+
41
+ Ask rather than guess: which jobs deserve a node at all, how jobs split into streams, what to call a stream, and any environment name that is computed rather than written literally.
42
+
43
+ ## Step 5: Write the accepted graph
44
+
45
+ Write the accepted streams to a JSON file and pass it in. `repo` defaults to the repo you are in, so leave it out.
46
+
47
+ ```
48
+ assist releases configure --scope project --streams /tmp/streams.json
49
+ ```
50
+
51
+ ```json
52
+ [
53
+ {
54
+ "name": "Web App",
55
+ "workflow": "release.yml",
56
+ "nodes": [
57
+ { "id": "build", "kind": "build" },
58
+ { "id": "dev", "environment": "dev" },
59
+ { "id": "promote", "kind": "gate" },
60
+ { "id": "uk-prod", "environment": "UK Production", "label": "uk-prod" }
61
+ ],
62
+ "edges": [
63
+ ["build", "dev"],
64
+ ["dev", "promote"],
65
+ ["promote", "uk-prod"]
66
+ ]
67
+ }
68
+ ]
69
+ ```
70
+
71
+ The array is validated against the config schema as a whole, so a bad node or a dangling edge id leaves the config file untouched and the errors are printed. Streams declared for other repos are kept; the ones for this repo are replaced.
72
+
73
+ Report what was written and where, quoting the command's own output.