@staff0rd/assist 0.684.0 → 0.684.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 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
 
@@ -453,7 +454,7 @@ releases:
453
454
  ```
454
455
 
455
456
  - `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.
457
+ - `/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
458
 
458
459
  ## Parallel work
459
460
 
@@ -489,7 +490,7 @@ A restart kills every managed session's pty, which also kills any background tas
489
490
  - `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
491
  - `branch.prefix` — when set (e.g. `sw`), `assist branch <slug>` prepends `<prefix>/` to the branch name
491
492
  - `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`
493
+ - `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
494
  - `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
495
 
495
496
  ## 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.