@jc_stack/ez-github 0.1.0-beta.4 → 0.1.0-beta.7

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/CHANGELOG.md CHANGED
@@ -1,5 +1,25 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.0-beta.7
4
+
5
+ - Run the runtime image on the October 2026 Node 22 security release (`node:22.23.4-bookworm-slim`, digest pinned); no CLI behavior changes.
6
+
7
+ ## 0.1.0-beta.6
8
+
9
+ - Validate kanban fields and values before writing, compare numeric readback as numbers, and confirm newly created comments through provider readback.
10
+ - Add `kanban`: basic task-board commands for any agent (`board`, `list`, `show`, `add`, `move`, `set`, `comment`) over a GitHub Project, with JSON output and readback after each write. Tracker-neutral verbs; no workflow rules. Declared `requiresReview: false` because it only changes the team's own task board.
11
+
12
+ ## 0.1.0-beta.5
13
+
14
+ - Requires Ez core 0.1.0-beta.50 or newer for the manifest example.
15
+ Older cores refuse the update and retain the installed version.
16
+ - Add representative manifest examples for tool discovery; align the private issue adapter on beta.2.
17
+
18
+ - Add the read-only `github-work` command: a Project work eligibility check for core's owner-configured schedule preflight. It reads the complete Project through the private profile with caller-supplied field filters and optional `ez-work` metadata, returns only eligibility, IDs and a stable fingerprint, and makes no task writes or agent dispatch; `--observe-all` fingerprints complete Project state for changed-mode admission. Existing `github`/Git commands are unchanged.
19
+ - Work-check fails closed (error, exit 1) for filter fields that are not single-select/text, unreadable filtered values and over-long task identities; verify now syntax-checks `bin/work-check.mjs`.
20
+ - Preserve runtime CLI access when Ez snapshots package files with private modes by assigning the copied command to the non-root container user.
21
+ - Install GitHub CLI from its signed upstream package repository so current commands such as Projects are available.
22
+
3
23
  ## 0.1.0-beta.4
4
24
 
5
25
  - Add the required Ez release contract so the native updater can admit the package.
package/CONTRIBUTING.md CHANGED
@@ -1,9 +1,11 @@
1
1
  # Contributing
2
2
 
3
3
  Use one isolated worktree and branch per change. Preserve unrelated state.
4
- Run npm run verify, npm run release:check, npm audit --omit=dev and git diff --check. Package with npm pack --ignore-scripts;
4
+ Run pnpm run verify, pnpm run release:check, npm audit --omit=dev and git diff --check. Package with npm pack --ignore-scripts;
5
5
  test and build the extracted package and verify Ez manager installation.
6
6
  Credentials, argument transport and cancellation changes require negative tests.
7
+ Run `node scripts/runtime-smoke.mjs` to verify the packed image with private
8
+ snapshot permissions, non-root CLI access and the native GitHub Projects command.
7
9
  Never put provider credentials or private records in tests or PRs.
8
10
  Independent review, CI and maintainer authorization precede merge/publication.
9
11
  Keep the worktree while review or QA is open. Publication is a separate decision.
package/Dockerfile CHANGED
@@ -1,8 +1,16 @@
1
- FROM node:22.22.0-bookworm-slim@sha256:dd9d21971ec4395903fa6143c2b9267d048ae01ca6d3ea96f16cb30df6187d94 AS runtime
2
- RUN apt-get update && apt-get install -y --no-install-recommends git gh ca-certificates && rm -rf /var/lib/apt/lists/*
1
+ FROM node:22.23.4-bookworm-slim@sha256:de170b39439eb0e5a3444ad7d60b015614a381e10fecae2e30ec9e735122f38d AS runtime
2
+ RUN apt-get update \
3
+ && apt-get install -y --no-install-recommends git ca-certificates wget \
4
+ && mkdir -p -m 755 /etc/apt/keyrings \
5
+ && wget -qO /etc/apt/keyrings/githubcli-archive-keyring.gpg https://cli.github.com/packages/githubcli-archive-keyring.gpg \
6
+ && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
7
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" > /etc/apt/sources.list.d/github-cli.list \
8
+ && apt-get update \
9
+ && apt-get install -y --no-install-recommends gh \
10
+ && rm -rf /var/lib/apt/lists/*
3
11
  RUN mkdir /state /repos && chown node:node /state /repos && chmod 700 /state /repos
4
12
  ENV GH_CONFIG_DIR=/state/gh XDG_CONFIG_HOME=/state/config GIT_CONFIG_GLOBAL=/state/gitconfig GH_PROMPT_DISABLED=1
5
- COPY bin /app/bin
13
+ COPY --chown=node:node bin /app/bin
6
14
  USER node
7
15
  WORKDIR /repos
8
16
  CMD ["sleep", "infinity"]
package/README.md CHANGED
@@ -4,8 +4,8 @@ Thin native GitHub CLI and Git plugin for Ez. Private per-agent profile and writ
4
4
  repository volume; no provider API implementation or workflow engine.
5
5
 
6
6
  Requires Node 22+, Docker/Compose and Ez with the cancellation fix (manager release
7
- 0.1.0-beta.13 or newer). Obtain `@jc_stack/ez-github@0.1.0-beta.4` with
8
- `npm pack @jc_stack/ez-github@0.1.0-beta.4 --ignore-scripts`, extract into a permanent
7
+ 0.1.0-beta.60 or newer). Obtain `@jc_stack/ez-github@0.1.0-beta.7` with
8
+ `npm pack @jc_stack/ez-github@0.1.0-beta.7 --ignore-scripts`, extract into a permanent
9
9
  private tools directory, and inspect the extracted package.
10
10
 
11
11
  Inspect this directory with `ez plugins inspect github --source /absolute/package`,
@@ -25,9 +25,29 @@ not encrypted by a keyring. No unattended identity creation or token display.
25
25
 
26
26
  Uninstall preserves data. Revocation is separate in GitHub's authorized applications.
27
27
  Rollback retains volumes; do not run concurrent writers on one repository. Test with
28
- `npm run verify`, `npm run release:check`, Docker build and manager dispatch. Live GitHub verification needs consent.
28
+ `pnpm run verify`, `pnpm run release:check`, Docker build and manager dispatch. Live GitHub verification needs consent.
29
29
 
30
- Testing beta: Debian supplies Git/gh updates at image build; the installed image
30
+ Testing beta: Debian supplies Git and the signed upstream GitHub CLI repository
31
+ supplies gh at image build; the installed image
31
32
  is retained by Ez's source revision. Capture `gh --version` and `git --version` during QA.
32
33
  Fresh isolated Docker installation and PA authentication are tested; a separate
33
34
  machine/reboot and a fresh OAuth consent in that environment remain stable-release QA.
35
+
36
+ Requires Ez core 0.1.0-beta.60 or newer for the manifest example.
37
+ Older cores refuse the update and retain the installed version.
38
+
39
+ ## Kanban
40
+
41
+ `ez kanban` gives agents basic task-board operations: `board`, `list`, `show`,
42
+ `add`, `move`, `set` and `comment`, with JSON output and a readback after every
43
+ write. The verbs are tracker-neutral; this adapter stores the board in a GitHub
44
+ Project through the private profile, so another tracker can later provide the
45
+ same commands. It holds no workflow rules. Example:
46
+ `ez kanban list --board OWNER/NUMBER --column Ready`. The login needs the
47
+ `project` scope. See skills/kanban/SKILL.md.
48
+
49
+ ## Read-only work queue preflight
50
+
51
+ `ez github-work --project PROJECT_NODE_ID --field Role=CIO --field Status=Ready --require-metadata` reads the complete Project through the private GitHub profile, returning only eligibility, IDs and a stable fingerprint. Field names/values are caller supplied; this adapter contains no role, model or workflow routing. `ez-work` JSON on an issue records `schemaVersion:1`, `identity`, optional `notBefore` and `freshUntil`; requiring metadata also requires a valid unexpired freshness clock. Missing provider/schema coverage is an error, never empty work. A malformed, ambiguous or over-long (200+ characters) `ez-work` block on any open item blocks the whole queue (the check errors, fail closed) by design; fix or remove the block to unblock it. Filter fields must be single-select or text, and an unreadable value for a filtered field is an error. This command makes no task writes and starts no agent. Core's installed plugin preflight calls it before creating an LLM run. Existing native `github`/Git commands are unchanged. Managed snippet: unnecessary; installed help/skill owns discovery.
52
+
53
+ For coordination, `github-work --project PROJECT_NODE_ID --observe-all` fingerprints complete Project state, including waiting, closed and archived items. It ignores queue clocks/metadata and permits a changed-state check even for an empty Project. Use it with native changed-mode admission; keep role queue selection on the filtered path.
@@ -1,2 +1,3 @@
1
- Git is licensed under GPL-2.0; GitHub CLI under MIT. Debian distributes their binaries
2
- and licenses under /usr/share/doc. Node.js is MIT licensed. No upstream source is forked.
1
+ Git is licensed under GPL-2.0; GitHub CLI under MIT. Debian distributes Git;
2
+ the signed upstream GitHub CLI repository distributes gh. Installed licenses
3
+ are under /usr/share/doc. Node.js is MIT licensed. No upstream source is forked.
package/bin/github.mjs CHANGED
@@ -11,7 +11,7 @@ export function command(args) {
11
11
  if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href) {
12
12
  process.umask(0o077);
13
13
  const args=process.argv.slice(2);
14
- if(args[0]==='--version') console.log('ez-github 0.1.0-beta.4');
14
+ if(args[0]==='--version') console.log('ez-github 0.1.0-beta.7');
15
15
  else if(!args.length||args[0]==='--help') console.log('ez github doctor | gh <native arguments> | git <native arguments>\nPrivate repositories: /repos. Native stdin, output and exit codes. Read skills/github/SKILL.md for OAuth onboarding.');
16
16
  else {
17
17
  try {
package/bin/kanban.mjs ADDED
@@ -0,0 +1,166 @@
1
+ #!/usr/bin/env node
2
+ // Basic kanban for agents: board, list, show, add, move, set, comment.
3
+ // The verbs are tracker-neutral; this adapter stores the board in a GitHub
4
+ // Project (v2) through the private gh profile. Another tracker can provide the
5
+ // same verbs and output shape. No workflow rules, gates or routing live here.
6
+ import {execFile} from 'node:child_process';
7
+ import {promisify} from 'node:util';
8
+ import {parseArgs} from 'node:util';
9
+ import {pathToFileURL} from 'node:url';
10
+
11
+ const ITEM=`fragment I on ProjectV2Item{id isArchived content{__typename ...on Issue{number title url state repository{nameWithOwner}} ...on PullRequest{number title url prState:state repository{nameWithOwner}} ...on DraftIssue{title}} fieldValues(first:50){nodes{
12
+ ...on ProjectV2ItemFieldSingleSelectValue{name field{...on ProjectV2FieldCommon{name}}}
13
+ ...on ProjectV2ItemFieldTextValue{text field{...on ProjectV2FieldCommon{name}}}
14
+ ...on ProjectV2ItemFieldDateValue{date field{...on ProjectV2FieldCommon{name}}}
15
+ ...on ProjectV2ItemFieldNumberValue{number field{...on ProjectV2FieldCommon{name}}}
16
+ ...on ProjectV2ItemFieldIterationValue{title field{...on ProjectV2FieldCommon{name}}}}}}`;
17
+ const PROJECT=`fragment P on ProjectV2{id title fields(first:100){nodes{...on ProjectV2FieldCommon{id name dataType} ...on ProjectV2SingleSelectField{options{id name}}}} items(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{...I}}}`;
18
+ const BOARD=`query($owner:String!,$number:Int!,$after:String){repositoryOwner(login:$owner){...on User{projectV2(number:$number){...P}} ...on Organization{projectV2(number:$number){...P}}}} ${PROJECT} ${ITEM}`;
19
+ const NODE=`query($id:ID!){node(id:$id){...I}} ${ITEM}`;
20
+ export const HELP=`ez kanban <command> --board OWNER/NUMBER [options]
21
+ board columns and fields
22
+ list [--column C] [--field NAME=VALUE]... cards (no bodies)
23
+ show CARD card with body and comments
24
+ add --repo OWNER/REPO --title T [--body T | --body-file F] [--column C] [--set NAME=VALUE]...
25
+ move CARD COLUMN change the card's column, read back
26
+ set CARD NAME=VALUE... change fields (text, date YYYY-MM-DD, number, option); NAME= clears
27
+ comment CARD (--body T | --body-file F)
28
+ CARD is the card id from list, OWNER/REPO#N or the issue/PR URL. --column-field
29
+ names the column field (default Status). Output is JSON; errors exit 1.`;
30
+
31
+ const plain=item=>{
32
+ const c=item.content??{},fields={};
33
+ for(const v of item.fieldValues?.nodes??[]) if(v?.field?.name && v.field.name!=='Title') fields[v.field.name]=v.name??v.text??v.date??v.number??v.title??null;
34
+ return {card:item.id,type:c.__typename==='DraftIssue'?'draft':c.__typename==='PullRequest'?'pr':'issue',
35
+ ref:c.repository?`${c.repository.nameWithOwner}#${c.number}`:null,url:c.url??null,title:c.title??null,
36
+ state:(c.state??c.prState)?.toLowerCase()??null,archived:!!item.isArchived,fields};
37
+ };
38
+ export function parseBoard(text) {
39
+ const m=/^([A-Za-z0-9-]+)\/(\d+)$/.exec(text??'');
40
+ if(!m) throw Error('Use --board OWNER/NUMBER');
41
+ return {owner:m[1],number:Number(m[2])};
42
+ }
43
+ export function kanban({gh,columnField='Status'}) {
44
+ const json=async args=>JSON.parse(await gh(args));
45
+ const gql=async(query,vars)=>{
46
+ const value=await json(['api','graphql','-f',`query=${query}`,...Object.entries(vars).flatMap(([k,v])=>[typeof v==='number'?'-F':'-f',`${k}=${v}`])]);
47
+ if(value.errors?.length) throw Error(`GitHub: ${value.errors[0].message}`);
48
+ return value.data;
49
+ };
50
+ const read=async board=>{
51
+ const {owner,number}=parseBoard(board);let after,project,items=[];
52
+ do {
53
+ const data=await gql(BOARD,{owner,number,...(after?{after}:{})});
54
+ project=data.repositoryOwner?.projectV2;
55
+ if(!project) throw Error(`Board ${board} not found or not readable`);
56
+ items.push(...project.items.nodes);
57
+ after=project.items.pageInfo.hasNextPage?project.items.pageInfo.endCursor:null;
58
+ } while(after);
59
+ const fields=project.fields.nodes.filter(f=>f?.name);
60
+ return {owner,number,id:project.id,title:project.title,fields,items:items.map(plain)};
61
+ };
62
+ const field=(b,name)=>{const f=b.fields.find(x=>x.name.toLowerCase()===name.toLowerCase());if(!f) throw Error(`No field "${name}" on this board`);return f;};
63
+ const find=(b,ref)=>{
64
+ const url=/github\.com\/([^/]+\/[^/]+)\/(?:issues|pull)\/(\d+)/.exec(ref??'');
65
+ const key=url?`${url[1]}#${url[2]}`:ref;
66
+ const card=b.items.find(x=>x.card===ref||x.ref?.toLowerCase()===key?.toLowerCase());
67
+ if(!card) throw Error(`Card ${ref} is not on this board`);
68
+ return card;
69
+ };
70
+ const readback=async id=>plain((await gql(NODE,{id})).node);
71
+ const editArgs=(b,name,value)=>{
72
+ const f=field(b,name),base=['--field-id',f.id];
73
+ if(value==='') return [...base,'--clear'];
74
+ if(f.dataType==='SINGLE_SELECT') {
75
+ const o=f.options.find(x=>x.name.toLowerCase()===value.toLowerCase());
76
+ if(!o) throw Error(`"${value}" is not an option of ${f.name}: ${f.options.map(x=>x.name).join(', ')}`);
77
+ return [...base,'--single-select-option-id',o.id];
78
+ }
79
+ if(f.dataType==='DATE' && (!/^\d{4}-\d{2}-\d{2}$/.test(value)||!Number.isFinite(Date.parse(value))||new Date(value).toISOString().slice(0,10)!==value)) throw Error(`${f.name} takes a date YYYY-MM-DD`);
80
+ if(f.dataType==='NUMBER' && (!value.trim()||!Number.isFinite(Number(value)))) throw Error(`${f.name} takes a number`);
81
+ const flag={TEXT:'--text',DATE:'--date',NUMBER:'--number'}[f.dataType];
82
+ if(!flag) throw Error(`${f.name} (${f.dataType}) cannot be set here`);
83
+ return [...base,flag,f.dataType==='NUMBER'?String(Number(value)):value];
84
+ };
85
+ const setAll=async(b,card,pairs)=>{
86
+ const edits=pairs.map(([name,value])=>editArgs(b,name,value));
87
+ for(const args of edits) await gh(['project','item-edit','--id',card,'--project-id',b.id,...args]);
88
+ const after=await readback(card);
89
+ for(const [name,value] of pairs) {
90
+ const f=field(b,name),got=after.fields[f.name]??'';
91
+ const matches=f.dataType==='NUMBER'&&value!==''?typeof got==='number'&&got===Number(value):String(got).toLowerCase()===String(value).toLowerCase();
92
+ if(!matches) throw Error(`Readback: ${name} is "${got}", expected "${value}"`);
93
+ }
94
+ return after;
95
+ };
96
+ const body=o=>o.body!==undefined?['--body',o.body]:o['body-file']!==undefined?['--body-file',o['body-file']]:null;
97
+ return {
98
+ async board(o) {const b=await read(o.board);return {board:o.board,title:b.title,columns:field(b,columnField).options?.map(x=>x.name)??[],fields:b.fields.map(f=>({name:f.name,type:f.dataType.toLowerCase(),...(f.options?{options:f.options.map(x=>x.name)}:{})}))};},
99
+ async list(o) {
100
+ const b=await read(o.board),filters=pairs(o.field);
101
+ if(o.column) filters.push([columnField,o.column]);
102
+ return b.items.filter(x=>!x.archived&&filters.every(([n,v])=>String(x.fields[field(b,n).name]??'').toLowerCase()===v.toLowerCase()));
103
+ },
104
+ async show(o,[ref]) {
105
+ const card=find(await read(o.board),ref);
106
+ if(card.type==='draft') return card;
107
+ const detail=await json([card.type==='pr'?'pr':'issue','view',card.url,'--json','body,comments']);
108
+ return {...card,body:detail.body,comments:(detail.comments??[]).map(c=>({author:c.author?.login??null,at:c.createdAt,body:c.body,url:c.url}))};
109
+ },
110
+ async add(o) {
111
+ if(!/^[\w.-]+\/[\w.-]+$/.test(o.repo??'')||!o.title) throw Error('add needs --repo OWNER/REPO and --title');
112
+ const b=await read(o.board);
113
+ const pre=[...(o.column?[[columnField,o.column]]:[]),...pairs(o.set)];
114
+ for(const [name,value] of pre) editArgs(b,name,value);
115
+ const url=(await gh(['issue','create','--repo',o.repo,'--title',o.title,...(body(o)??['--body',''])])).trim().split('\n').pop();
116
+ const {id}=await json(['project','item-add',String(b.number),'--owner',b.owner,'--url',url,'--format','json']);
117
+ return pre.length?setAll(b,id,pre):readback(id);
118
+ },
119
+ async move(o,[ref,column]) {
120
+ if(!ref||!column) throw Error('move needs CARD and COLUMN');
121
+ const b=await read(o.board);return setAll(b,find(b,ref).card,[[columnField,column]]);
122
+ },
123
+ async set(o,[ref,...rest]) {
124
+ const list=pairs(rest);if(!ref||!list.length) throw Error('set needs CARD and NAME=VALUE');
125
+ const b=await read(o.board);return setAll(b,find(b,ref).card,list);
126
+ },
127
+ async comment(o,[ref]) {
128
+ const text=body(o);if(!text) throw Error('comment needs --body or --body-file');
129
+ const card=find(await read(o.board),ref);
130
+ if(card.type==='draft') throw Error('Draft cards take no comments; convert it to an issue');
131
+ const url=(await gh([card.type==='pr'?'pr':'issue','comment',card.url,...text])).trim();
132
+ const id=/#issuecomment-(\d+)$/.exec(url)?.[1];
133
+ if(!id) throw Error('Comment write returned no comment id');
134
+ const saved=await json(['api',`repos/${card.ref.split('#')[0]}/issues/comments/${id}`]);
135
+ if(saved.html_url!==url) throw Error('Comment readback did not match the created comment');
136
+ return {card:card.card,ref:card.ref,comment:saved.html_url};
137
+ },
138
+ };
139
+ }
140
+ export function pairs(values=[]) {
141
+ return values.map(s=>{const at=s.indexOf('=');if(at<1) throw Error(`Use NAME=VALUE, not "${s}"`);return [s.slice(0,at),s.slice(at+1)];});
142
+ }
143
+ export async function main(argv,gh) {
144
+ const {values,positionals}=parseArgs({args:argv,allowPositionals:true,options:{
145
+ board:{type:'string'},column:{type:'string'},'column-field':{type:'string'},field:{type:'string',multiple:true},
146
+ set:{type:'string',multiple:true},repo:{type:'string'},title:{type:'string'},body:{type:'string'},'body-file':{type:'string'},help:{type:'boolean'}}});
147
+ const [verb,...rest]=positionals;
148
+ if(values.help||!verb) return HELP;
149
+ const k=kanban({gh,columnField:values['column-field']});
150
+ if(!Object.hasOwn(k,verb)) throw Error(`Unknown command ${verb}. ${HELP}`);
151
+ return JSON.stringify(await k[verb](values,rest),null,2);
152
+ }
153
+ export function nativeGh() {
154
+ const env={...process.env};
155
+ for(const key of ['GH_TOKEN','GITHUB_TOKEN','GH_ENTERPRISE_TOKEN','GITHUB_ENTERPRISE_TOKEN']) delete env[key];
156
+ const run=promisify(execFile);
157
+ return async args=>{
158
+ try {return (await run('gh',args,{env,maxBuffer:32*1024*1024,timeout:60000})).stdout;}
159
+ catch(error) {throw Error((error.stderr||error.message||'gh failed').toString().trim().split('\n').pop());}
160
+ };
161
+ }
162
+ if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href) {
163
+ process.umask(0o077);
164
+ try {console.log(await main(process.argv.slice(2),nativeGh()));}
165
+ catch(error) {console.error(error.message);process.exitCode=1;}
166
+ }
@@ -0,0 +1,70 @@
1
+ #!/usr/bin/env node
2
+ import {execFile} from 'node:child_process';
3
+ import {promisify} from 'node:util';
4
+ import {createHash} from 'node:crypto';
5
+ import {parseArgs} from 'node:util';
6
+ import {pathToFileURL} from 'node:url';
7
+
8
+ const query=`query($project:ID!,$after:String){node(id:$project){...on ProjectV2{fields(first:100){nodes{...on ProjectV2FieldCommon{name dataType}}pageInfo{hasNextPage}}items(first:100,after:$after){nodes{id isArchived updatedAt fieldValues(first:100){nodes{...on ProjectV2ItemFieldSingleSelectValue{name field{...on ProjectV2FieldCommon{name}}}...on ProjectV2ItemFieldTextValue{text field{...on ProjectV2FieldCommon{name}}}}pageInfo{hasNextPage}}content{...on Issue{body state updatedAt}...on DraftIssue{body updatedAt}...on PullRequest{body state updatedAt}}}pageInfo{hasNextPage endCursor}}}}}`;
9
+ const FILTERABLE_TYPES=['SINGLE_SELECT','TEXT'],MAX_IDENTITY=200;
10
+ export function selectWork(items,fields,filters,requireMetadata=false,now=Date.now(),observeAll=false) {
11
+ if(observeAll && (filters.length || requireMetadata)) throw Error('Observe-all cannot filter or require queue metadata');
12
+ // fields: field names, or {name,dataType} objects as read from the Project.
13
+ const known=new Map(fields.map(f=>typeof f==='string'?[f,{name:f}]:[f.name,f]));
14
+ for(const [name] of filters) {
15
+ const field=known.get(name);
16
+ if(!field) throw Error('Configured Project field is unavailable');
17
+ if(field.dataType!==undefined && !FILTERABLE_TYPES.includes(field.dataType)) throw Error('Configured Project field must be single-select or text');
18
+ }
19
+ const filtered=new Set(filters.map(([name])=>name));
20
+ const candidates=[];
21
+ for(const item of items) {
22
+ if(item.fieldValues?.pageInfo?.hasNextPage) throw Error('Incomplete item field coverage');
23
+ const values=Object.fromEntries(item.fieldValues.nodes.filter(v=>v.field).map(v=>{
24
+ const value=v.name??v.text;
25
+ if(filtered.has(v.field.name) && typeof value!=='string') throw Error('Unreadable value for a filtered Project field');
26
+ return [v.field.name,value];
27
+ }));
28
+ if(observeAll) {candidates.push({id:item.id,isArchived:item.isArchived,state:item.content?.state,updatedAt:item.updatedAt,contentUpdatedAt:item.content?.updatedAt,fields:values});continue;}
29
+ if(item.isArchived || item.content?.state==='CLOSED') continue;
30
+ if(!filters.every(([name,value])=>values[name]===value)) continue;
31
+ let metadata;
32
+ const blocks=[...(item.content?.body??'').matchAll(/```ez-work\s*\n([\s\S]*?)\n```/g)];
33
+ if(blocks.length>1) throw Error('Ambiguous task metadata');
34
+ if(blocks.length) {
35
+ metadata=JSON.parse(blocks[0][1]);
36
+ if(metadata.schemaVersion!==1 || typeof metadata.identity!=='string' || !metadata.identity.trim() || metadata.identity.length>MAX_IDENTITY) throw Error('Invalid task metadata');
37
+ for(const key of ['notBefore','freshUntil']) if(metadata[key]!==undefined && (!/T.*(?:Z|[+-]\d\d:\d\d)$/.test(metadata[key]) || !Number.isFinite(Date.parse(metadata[key])))) throw Error('Invalid task clock');
38
+ }
39
+ if(requireMetadata && (!metadata || !metadata.freshUntil)) continue;
40
+ if(metadata?.notBefore && Date.parse(metadata.notBefore)>now) continue;
41
+ if(metadata?.freshUntil && Date.parse(metadata.freshUntil)<now) continue;
42
+ candidates.push({id:item.id,updatedAt:item.updatedAt,contentUpdatedAt:item.content?.updatedAt,fields:values,...(metadata ? {identity:metadata.identity,notBefore:metadata.notBefore,freshUntil:metadata.freshUntil} : {})});
43
+ }
44
+ candidates.sort((a,b)=>a.id.localeCompare(b.id));
45
+ return {schemaVersion:1,eligible:observeAll || candidates.length>0,count:candidates.length,observedAt:new Date(now).toISOString(),fingerprint:createHash('sha256').update(JSON.stringify(candidates)).digest('hex'),items:candidates.map(i=>({id:i.id,...(i.identity?{identity:i.identity}:{})}))};
46
+ }
47
+ export async function checkProject(project,filters,requireMetadata,run=promisify(execFile),observeAll=false) {
48
+ if(typeof project!=='string' || !/^PVT_[A-Za-z0-9_-]+$/.test(project)) throw Error('Supply the exact Project node ID');
49
+ const env={...process.env};for(const key of ['GH_TOKEN','GITHUB_TOKEN','GH_ENTERPRISE_TOKEN','GITHUB_ENTERPRISE_TOKEN'])delete env[key];
50
+ const items=[],seen=new Set();let after,fields;
51
+ do {
52
+ const args=['api','graphql','-f',`query=${query}`,'-f',`project=${project}`,...(after?['-f',`after=${after}`]:[])];
53
+ const {stdout}=await run('gh',args,{env,maxBuffer:16*1024*1024,timeout:30000});const value=JSON.parse(stdout),node=value.data?.node;
54
+ if(value.errors?.length || !node?.items || node.fields.pageInfo.hasNextPage) throw Error('Project read incomplete or unavailable');
55
+ fields=node.fields.nodes.map(f=>({name:f.name,dataType:f.dataType}));for(const item of node.items.nodes){if(seen.has(item.id))throw Error('Repeated Project item');seen.add(item.id);items.push(item);}
56
+ if(!node.items.pageInfo.hasNextPage)break;
57
+ const next=node.items.pageInfo.endCursor;if(!next || next===after)throw Error('Invalid Project cursor');after=next;
58
+ }while(true);
59
+ return selectWork(items,fields,filters,requireMetadata,Date.now(),observeAll);
60
+ }
61
+ if(process.argv[1] && import.meta.url===pathToFileURL(process.argv[1]).href) {
62
+ try {
63
+ const {values:v}=parseArgs({options:{project:{type:'string'},field:{type:'string',multiple:true},'require-metadata':{type:'boolean'},'observe-all':{type:'boolean'},help:{type:'boolean'}}});
64
+ if(v.help)console.log('ez github-work --project PROJECT_NODE_ID [--field NAME=VALUE] [--require-metadata] [--observe-all]\nRead-only complete Project queue preflight. Emits schemaVersion, eligible, count, fingerprint, observedAt and item IDs. Task metadata is optional fenced ez-work JSON: schemaVersion:1, identity (max 200 characters), notBefore, freshUntil. A malformed or ambiguous ez-work block on any open item blocks the whole queue (error, fail closed) by design. --require-metadata requires freshUntil; expired/future tasks are ineligible. Observe-all fingerprints every item including closed/archived/future/expired work, ignores queue metadata and always permits a changed-state coordination check. It cannot be combined with queue filters. Filter fields must be single-select or text. Errors never mean empty queue.');
65
+ else {
66
+ const filters=(v.field??[]).map(s=>{const at=s.indexOf('=');if(at<1 || at===s.length-1)throw Error('Use --field NAME=VALUE');return [s.slice(0,at),s.slice(at+1)];});
67
+ console.log(JSON.stringify(await checkProject(v.project,filters,v['require-metadata'],undefined,v['observe-all'])));
68
+ }
69
+ }catch(error){console.error(error.message);process.exitCode=1;}
70
+ }
@@ -1 +1,42 @@
1
- {"schemaVersion":2,"services":{"plugin":{"buildTarget":"runtime","volumes":{"profile":"/state","repositories":"/repos"},"workspace":true,"healthcheck":["node","/app/bin/github.mjs","--version"],"memoryMiB":256}},"commands":{"github":{"service":"plugin","argv":["node","/app/bin/github.mjs"]}}}
1
+ {
2
+ "schemaVersion": 2,
3
+ "services": {
4
+ "plugin": {
5
+ "buildTarget": "runtime",
6
+ "volumes": {
7
+ "profile": "/state",
8
+ "repositories": "/repos"
9
+ },
10
+ "workspace": true,
11
+ "healthcheck": [
12
+ "node",
13
+ "/app/bin/github.mjs",
14
+ "--version"
15
+ ],
16
+ "memoryMiB": 256
17
+ }
18
+ },
19
+ "commands": {
20
+ "github": {
21
+ "service": "plugin",
22
+ "argv": [
23
+ "node",
24
+ "/app/bin/github.mjs"
25
+ ]
26
+ },
27
+ "github-work": {
28
+ "service": "plugin",
29
+ "argv": [
30
+ "node",
31
+ "/app/bin/work-check.mjs"
32
+ ]
33
+ },
34
+ "kanban": {
35
+ "service": "plugin",
36
+ "argv": [
37
+ "node",
38
+ "/app/bin/kanban.mjs"
39
+ ]
40
+ }
41
+ }
42
+ }
package/ez-plugin.json CHANGED
@@ -1 +1,43 @@
1
- {"schemaVersion":1,"id":"github","version":"0.1.0-beta.4","description":"GitHub CLI and Git with a private agent profile and writable repositories","commands":{"github":{"executable":"bin/github.mjs","args":[],"exposure":{"receivesExternalContent":true,"sendsExternally":true,"changesRecords":true,"requiresReview":true}}},"skills":["skills/github/SKILL.md"]}
1
+ {
2
+ "schemaVersion": 1,
3
+ "id": "github",
4
+ "version": "0.1.0-beta.7",
5
+ "description": "GitHub CLI and Git with a private agent profile and writable repositories",
6
+ "example": "github gh repo view OWNER/REPO",
7
+ "commands": {
8
+ "github": {
9
+ "executable": "bin/github.mjs",
10
+ "args": [],
11
+ "exposure": {
12
+ "receivesExternalContent": true,
13
+ "sendsExternally": true,
14
+ "changesRecords": true,
15
+ "requiresReview": true
16
+ }
17
+ },
18
+ "github-work": {
19
+ "executable": "bin/work-check.mjs",
20
+ "args": [],
21
+ "exposure": {
22
+ "receivesExternalContent": true,
23
+ "sendsExternally": false,
24
+ "changesRecords": false,
25
+ "requiresReview": false
26
+ }
27
+ },
28
+ "kanban": {
29
+ "executable": "bin/kanban.mjs",
30
+ "args": [],
31
+ "exposure": {
32
+ "receivesExternalContent": true,
33
+ "sendsExternally": true,
34
+ "changesRecords": true,
35
+ "requiresReview": false
36
+ }
37
+ }
38
+ },
39
+ "skills": [
40
+ "skills/github/SKILL.md",
41
+ "skills/kanban/SKILL.md"
42
+ ]
43
+ }
package/package.json CHANGED
@@ -1 +1,50 @@
1
- {"name":"@jc_stack/ez-github","version":"0.1.0-beta.4","description":"Native Git and GitHub CLI with private per-agent profiles for Ez","license":"MIT","engines":{"node":">=22"},"packageManager":"npm@10.9.4","repository":{"type":"git","url":"git+https://github.com/jdorado/ez_github.git"},"homepage":"https://github.com/jdorado/ez_github#readme","bugs":{"url":"https://github.com/jdorado/ez_github/issues"},"publishConfig":{"access":"public","tag":"latest"},"ezRelease":{"protocol":1,"kind":"plugin","stateSchema":1,"mainProtocol":1},"files":["bin","skills","test","scripts/release-check.mjs","Dockerfile",".dockerignore","ez-plugin.json","ez-deployment.json","README.md","LICENSE","CHANGELOG.md","CONTRIBUTING.md","SECURITY.md","THIRD_PARTY_NOTICES.md"],"scripts":{"test":"node --test test/*.test.mjs","verify":"node --check bin/github.mjs && npm test","release:check":"node scripts/release-check.mjs"}}
1
+ {
2
+ "name": "@jc_stack/ez-github",
3
+ "version": "0.1.0-beta.7",
4
+ "description": "Native Git and GitHub CLI with private per-agent profiles for Ez",
5
+ "license": "MIT",
6
+ "engines": {
7
+ "node": ">=22"
8
+ },
9
+ "packageManager": "pnpm@10.30.3",
10
+ "repository": {
11
+ "type": "git",
12
+ "url": "git+https://github.com/jdorado/ez_github.git"
13
+ },
14
+ "homepage": "https://github.com/jdorado/ez_github#readme",
15
+ "bugs": {
16
+ "url": "https://github.com/jdorado/ez_github/issues"
17
+ },
18
+ "publishConfig": {
19
+ "access": "public",
20
+ "tag": "latest"
21
+ },
22
+ "ezRelease": {
23
+ "protocol": 1,
24
+ "kind": "plugin",
25
+ "stateSchema": 1,
26
+ "mainProtocol": 1
27
+ },
28
+ "files": [
29
+ "bin",
30
+ "skills",
31
+ "test",
32
+ "scripts/release-check.mjs",
33
+ "Dockerfile",
34
+ ".dockerignore",
35
+ "ez-plugin.json",
36
+ "ez-deployment.json",
37
+ "README.md",
38
+ "LICENSE",
39
+ "CHANGELOG.md",
40
+ "CONTRIBUTING.md",
41
+ "SECURITY.md",
42
+ "THIRD_PARTY_NOTICES.md",
43
+ "pnpm-workspace.yaml"
44
+ ],
45
+ "scripts": {
46
+ "test": "node --test test/*.test.mjs",
47
+ "verify": "node --check bin/github.mjs && node --check bin/work-check.mjs && node --check bin/kanban.mjs && pnpm test",
48
+ "release:check": "node scripts/release-check.mjs"
49
+ }
50
+ }
@@ -0,0 +1,7 @@
1
+ # Hold third-party updates for seven days; reviewed first-party releases are exempt.
2
+ minimumReleaseAge: 10080
3
+ minimumReleaseAgeExclude:
4
+ - "@jc_stack/*"
5
+ - "@aifit/*"
6
+ trustPolicy: no-downgrade
7
+ blockExoticSubdeps: true
@@ -24,8 +24,13 @@ assert.deepEqual(manifest.commands.github, {
24
24
  requiresReview: true,
25
25
  },
26
26
  });
27
- assert.deepEqual(manifest.skills, ['skills/github/SKILL.md']);
27
+ assert.equal(manifest.commands['github-work'].executable, 'bin/work-check.mjs');
28
+ assert.equal(manifest.commands.kanban.executable, 'bin/kanban.mjs');
29
+ assert.equal(manifest.commands.kanban.exposure.requiresReview, false);
30
+ assert.deepEqual(manifest.skills, ['skills/github/SKILL.md', 'skills/kanban/SKILL.md']);
28
31
  assert.deepEqual(deployment.commands.github.argv, ['node', '/app/bin/github.mjs']);
32
+ assert.deepEqual(deployment.commands['github-work'].argv, ['node', '/app/bin/work-check.mjs']);
33
+ assert.deepEqual(deployment.commands.kanban.argv, ['node', '/app/bin/kanban.mjs']);
29
34
  assert.deepEqual(deployment.services.plugin.healthcheck, ['node', '/app/bin/github.mjs', '--version']);
30
35
 
31
36
  const version = spawnSync(process.execPath, ['bin/github.mjs', '--version'], {encoding: 'utf8'});
@@ -39,9 +44,14 @@ const [pack] = JSON.parse(execFileSync('npm', ['pack', '--dry-run', '--ignore-sc
39
44
  const files = pack.files.map(file => file.path);
40
45
  for (const required of [
41
46
  'bin/github.mjs',
47
+ 'bin/work-check.mjs',
48
+ 'bin/kanban.mjs',
49
+ 'skills/kanban/SKILL.md',
50
+ 'test/kanban.test.mjs',
42
51
  'scripts/release-check.mjs',
43
52
  'skills/github/SKILL.md',
44
53
  'test/cli.test.mjs',
54
+ 'test/work-check.test.mjs',
45
55
  'Dockerfile',
46
56
  '.dockerignore',
47
57
  'ez-plugin.json',
@@ -40,3 +40,7 @@ Do not create a test repository unless the owner requested that test.
40
40
  Manage with `ez plugins stop|start|status github`. Uninstall preserves both volumes.
41
41
  Revoking GitHub OAuth is separate from local logout. Back up volumes privately;
42
42
  never commit profiles. Shared host/Docker administrators remain trusted.
43
+
44
+ For native scheduled eligibility, `ez github-work --help` describes the read-only complete Project check, caller-supplied field filters and structured task metadata. Provider/schema errors are not an empty queue. By design, a malformed, ambiguous or over-long (200+ characters) `ez-work` block on any open item blocks the whole queue (the check errors, fail closed); fix or remove the block to unblock it. Filter fields must be single-select or text, and an unreadable value for a filtered field is an error. The checker neither writes tasks nor dispatches an agent. Native scheduling and each role's model remain with Ez.
45
+
46
+ For coordination, `github-work --project PROJECT_NODE_ID --observe-all` fingerprints complete Project state, including waiting, closed and archived items. It ignores queue clocks/metadata and permits a changed-state check even for an empty Project. Use it with native changed-mode admission; keep role queue selection on the filtered path.
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: kanban
3
+ description: Manage team tasks on a kanban board — list, add, move, update and comment on cards.
4
+ ---
5
+
6
+ `ez kanban` is a basic kanban board for agents: columns, cards and a few
7
+ fields. Use it to see what work exists, pick up a card, record progress and
8
+ hand work on. Run `ez kanban --help` for the exact arguments.
9
+
10
+ ```sh
11
+ ez kanban board --board OWNER/NUMBER # columns and fields
12
+ ez kanban list --board OWNER/NUMBER --column Ready
13
+ ez kanban show --board OWNER/NUMBER OWNER/REPO#12
14
+ ez kanban add --board OWNER/NUMBER --repo OWNER/REPO --title "…" --body-file /abs/brief.md --column Backlog --set "Due date=2026-10-20"
15
+ ez kanban move --board OWNER/NUMBER OWNER/REPO#12 "In Progress"
16
+ ez kanban set --board OWNER/NUMBER OWNER/REPO#12 "Due date=2026-10-21" Role=CIO
17
+ ez kanban comment --board OWNER/NUMBER OWNER/REPO#12 --body "Done: PR #40 merged"
18
+ ```
19
+
20
+ The board is the shared task list; the workspace's own instructions say which
21
+ board, which columns and what each field means. The tool keeps no workflow
22
+ rules: deciding when a card is ready, who takes it and when it is done is the
23
+ agents' judgment. Every write reads the card back and prints it, so the output
24
+ is the confirmation. If a write fails or is interrupted, `list` or `show` the
25
+ card before trying again; `add` has no idempotency key, so look for the card
26
+ before re-adding it.
27
+
28
+ This adapter keeps the board in a GitHub Project through the plugin's private
29
+ GitHub login (see the github skill for setup). The login needs Project access;
30
+ if `board` reports the board as not readable, run
31
+ `ez github gh auth refresh --hostname github.com --scopes project` with the
32
+ owner. Cards are issues, pull requests or drafts; comments go on the issue.
@@ -0,0 +1,132 @@
1
+ import {test} from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import {kanban,main,parseBoard,pairs} from '../bin/kanban.mjs';
4
+
5
+ const field=(id,name,dataType,options)=>({id,name,dataType,...(options?{options:options.map((n,i)=>({id:`${id}o${i}`,name:n}))}:{})});
6
+ const FIELDS=[field('F1','Status','SINGLE_SELECT',['Backlog','Ready','Done']),field('F2','Due date','DATE'),field('F3','Role','TEXT'),field('F4','Title','TEXT'),field('F5','Points','NUMBER')];
7
+ const value=(name,v)=>({...v,field:{name}});
8
+ const item=(id,number,fields,extra={})=>({id,isArchived:false,...extra,
9
+ content:{__typename:'Issue',number,title:`Task ${number}`,url:`https://github.com/o/r/issues/${number}`,state:'OPEN',repository:{nameWithOwner:'o/r'}},
10
+ fieldValues:{nodes:[value('Title',{text:`Task ${number}`}),...fields]}});
11
+
12
+ // A fake gh: two board pages, item-edit/item-add/issue calls recorded and applied.
13
+ function fakeGh(items) {
14
+ const calls=[],state=structuredClone(items);
15
+ const gh=async args=>{
16
+ calls.push(args);
17
+ if(args[0]==='api'&&args[1]==='repos/o/r/issues/comments/5') return JSON.stringify({html_url:'https://github.com/o/r/issues/1#issuecomment-5'});
18
+ if(args[0]==='api') {
19
+ const query=args.find(a=>a.startsWith('query=')),after=args.find(a=>a.startsWith('after='));
20
+ if(query.includes('node(id:')) {const id=args.find(a=>a.startsWith('id=')).slice(3);return JSON.stringify({data:{node:state.find(x=>x.id===id)}});}
21
+ const page=after?state.slice(1):state.slice(0,1);
22
+ return JSON.stringify({data:{repositoryOwner:{projectV2:{id:'PVT_1',title:'Board',fields:{nodes:FIELDS},items:{pageInfo:{hasNextPage:!after&&state.length>1,endCursor:'c1'},nodes:page}}}}});
23
+ }
24
+ if(args[0]==='project'&&args[1]==='item-edit') {
25
+ const it=state.find(x=>x.id===args[args.indexOf('--id')+1]),f=FIELDS.find(x=>x.id===args[args.indexOf('--field-id')+1]);
26
+ it.fieldValues.nodes=it.fieldValues.nodes.filter(v=>v.field.name!==f.name);
27
+ if(args.includes('--single-select-option-id')) it.fieldValues.nodes.push(value(f.name,{name:f.options.find(o=>o.id===args.at(-1)).name}));
28
+ if(args.includes('--date')) it.fieldValues.nodes.push(value(f.name,{date:args.at(-1)}));
29
+ if(args.includes('--text')) it.fieldValues.nodes.push(value(f.name,{text:args.at(-1)}));
30
+ if(args.includes('--number')) {
31
+ assert.match(args.at(-1),/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/,'native gh requires a decimal float argument');
32
+ it.fieldValues.nodes.push(value(f.name,{number:Number(args.at(-1))}));
33
+ }
34
+ return '{}';
35
+ }
36
+ if(args[0]==='issue'&&args[1]==='create') return 'Creating issue\nhttps://github.com/o/r/issues/9\n';
37
+ if(args[0]==='project'&&args[1]==='item-add') {state.push(item('PVTI_9',9,[]));return JSON.stringify({id:'PVTI_9'});}
38
+ if(args[0]==='issue'&&args[1]==='view') return JSON.stringify({body:'Do it',comments:[{author:{login:'a'},createdAt:'2026-10-16T00:00:00Z',body:'hi',url:'u'}]});
39
+ if(args[0]==='issue'&&args[1]==='comment') return 'https://github.com/o/r/issues/1#issuecomment-5\n';
40
+ throw Error(`unexpected gh ${args.join(' ')}`);
41
+ };
42
+ return {gh,calls,state};
43
+ }
44
+ const board=()=>fakeGh([item('PVTI_1',1,[value('Status',{name:'Backlog'}),value('Due date',{date:'2026-10-16'}),value('Role',{text:'CIO'})]),item('PVTI_2',2,[value('Status',{name:'Ready'})])]);
45
+
46
+ test('list reads every page and filters by column and field',async()=>{
47
+ const {gh}=board(),k=kanban({gh});
48
+ assert.equal((await k.list({board:'o/2'})).length,2);
49
+ const ready=await k.list({board:'o/2',column:'ready'});
50
+ assert.deepEqual(ready.map(x=>x.ref),['o/r#2']);
51
+ const cio=await k.list({board:'o/2',field:['Role=CIO']});
52
+ assert.deepEqual(cio[0],{card:'PVTI_1',type:'issue',ref:'o/r#1',url:'https://github.com/o/r/issues/1',title:'Task 1',state:'open',archived:false,fields:{Status:'Backlog','Due date':'2026-10-16',Role:'CIO'}});
53
+ });
54
+ test('board lists columns and fields',async()=>{
55
+ const out=await kanban({gh:board().gh}).board({board:'o/2'});
56
+ assert.deepEqual(out.columns,['Backlog','Ready','Done']);
57
+ assert.deepEqual(out.fields.find(f=>f.name==='Due date'),{name:'Due date',type:'date'});
58
+ });
59
+ test('move resolves the card by ref or URL and reads back',async()=>{
60
+ const {gh,calls}=board(),k=kanban({gh});
61
+ const moved=await k.move({board:'o/2'},['https://github.com/o/r/issues/1','Ready']);
62
+ assert.equal(moved.fields.Status,'Ready');
63
+ assert.ok(calls.some(a=>a.includes('--single-select-option-id')&&a.includes('F1o1')));
64
+ await assert.rejects(k.move({board:'o/2'},['o/r#1','Doing']),/not an option of Status: Backlog, Ready, Done/);
65
+ await assert.rejects(k.move({board:'o/2'},['o/r#7','Ready']),/not on this board/);
66
+ });
67
+ test('set changes date and text fields and clears with NAME=',async()=>{
68
+ const {gh}=board(),k=kanban({gh});
69
+ const out=await k.set({board:'o/2'},['o/r#1','Due date=2026-10-20','Role=Researcher']);
70
+ assert.equal(out.fields['Due date'],'2026-10-20');assert.equal(out.fields.Role,'Researcher');
71
+ await assert.rejects(k.set({board:'o/2'},['o/r#1','Due date=tomorrow']),/YYYY-MM-DD/);
72
+ await assert.rejects(k.set({board:'o/2'},['o/r#1','Priority=1']),/No field "Priority"/);
73
+ });
74
+ test('add creates the issue, puts it on the board and sets fields',async()=>{
75
+ const {gh,calls}=board(),k=kanban({gh});
76
+ const out=await k.add({board:'o/2',repo:'o/r',title:'New',body:'Why',column:'Backlog',set:['Due date=2026-10-17']});
77
+ assert.equal(out.card,'PVTI_9');assert.equal(out.fields.Status,'Backlog');assert.equal(out.fields['Due date'],'2026-10-17');
78
+ assert.deepEqual(calls.find(a=>a[1]==='create'),['issue','create','--repo','o/r','--title','New','--body','Why']);
79
+ await assert.rejects(k.add({board:'o/2',repo:'o/r',title:'X',set:['Nope=1']}),/No field "Nope"/);
80
+ assert.equal(calls.filter(a=>a[1]==='create').length,1);
81
+ });
82
+ test('show and comment use the issue',async()=>{
83
+ const {gh,calls}=board(),k=kanban({gh});
84
+ const shown=await k.show({board:'o/2'},['o/r#1']);
85
+ assert.equal(shown.body,'Do it');assert.equal(shown.comments[0].author,'a');
86
+ assert.deepEqual(await k.comment({board:'o/2',body:'Done: see PR'},['PVTI_1']),{card:'PVTI_1',ref:'o/r#1',comment:'https://github.com/o/r/issues/1#issuecomment-5'});
87
+ const write=calls.findIndex(a=>a[0]==='issue'&&a[1]==='comment');
88
+ assert.deepEqual(calls[write+1],['api','repos/o/r/issues/comments/5']);
89
+ await assert.rejects(k.comment({board:'o/2'},['PVTI_1']),/--body/);
90
+ });
91
+ test('argument errors and help',async()=>{
92
+ assert.throws(()=>parseBoard('o'),/OWNER\/NUMBER/);
93
+ assert.throws(()=>pairs(['x']),/NAME=VALUE/);
94
+ assert.match(await main([],async()=>''),/ez kanban/);
95
+ await assert.rejects(main(['delete','--board','o/2'],async()=>''),/Unknown command delete/);
96
+ await assert.rejects(main(['list'],async()=>''),/--board/);
97
+ });
98
+
99
+ test('invalid add options and values cause no writes',async()=>{
100
+ for(const options of [
101
+ {column:'Typo'},
102
+ {set:['Status=Typo']},
103
+ {set:['Due date=tomorrow']},
104
+ {set:['Due date=2026-02-31']},
105
+ {set:['Points=nope']},
106
+ {set:['Points= ']},
107
+ {set:['Nope=1']},
108
+ ]) {
109
+ const {gh,calls}=board();
110
+ await assert.rejects(kanban({gh}).add({board:'o/2',repo:'o/r',title:'New',...options}));
111
+ assert.equal(calls.filter(a=>a[0]!=='api').length,0);
112
+ }
113
+ });
114
+ test('set validates the whole batch before its first write',async()=>{
115
+ const {gh,calls}=board();
116
+ await assert.rejects(kanban({gh}).set({board:'o/2'},['o/r#1','Role=Researcher','Status=Typo']),/not an option/);
117
+ assert.equal(calls.filter(a=>a[0]!=='api').length,0);
118
+ });
119
+ test('number readback accepts canonical values and clearing',async()=>{
120
+ const {gh}=board(),k=kanban({gh});
121
+ for(const [input,expected] of [['1.0',1],['1e2',100],['0',0],[' 1 ',1],['0x10',16]]) {
122
+ const out=await k.set({board:'o/2'},['o/r#1',`Points=${input}`]);
123
+ assert.equal(out.fields.Points,expected);
124
+ }
125
+ assert.equal((await k.set({board:'o/2'},['o/r#1','Points='])).fields.Points,undefined);
126
+ });
127
+ test('comment fails when provider readback does not match',async()=>{
128
+ const fake=board();
129
+ const gh=async args=>args[0]==='api'&&args[1]==='repos/o/r/issues/comments/5'
130
+ ?JSON.stringify({html_url:'https://github.com/o/r/issues/1#issuecomment-6'}):fake.gh(args);
131
+ await assert.rejects(kanban({gh}).comment({board:'o/2',body:'Done'},['o/r#1']),/Comment readback/);
132
+ });
@@ -0,0 +1,63 @@
1
+ import test from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import {spawnSync} from 'node:child_process';
4
+ import {selectWork,checkProject} from '../bin/work-check.mjs';
5
+ const now=Date.parse('2026-10-07T12:00:00Z');
6
+ const item=(id,role='RoleX',status='Ready',metadata)=>({id,isArchived:false,updatedAt:'2026-10-07T10:00:00Z',content:{state:'OPEN',body:metadata?'```ez-work\n'+JSON.stringify(metadata)+'\n```':''},fieldValues:{pageInfo:{hasNextPage:false},nodes:[{field:{name:'Executor'},name:role},{field:{name:'Stage'},name:status}]}});
7
+ test('generic role/status selection and exact freshness gate',()=>{
8
+ const meta={schemaVersion:1,identity:'flow:object:occurrence',notBefore:'2026-10-07T11:00:00Z',freshUntil:'2026-10-08T12:00:00Z'};
9
+ const all=[item('A','RoleX','Ready',meta),item('B','RoleY'),item('C','RoleX','Ready',{...meta,freshUntil:'2026-10-06T12:00:00Z'}),item('D')];
10
+ const result=selectWork(all,['Executor','Stage'],[['Executor','RoleX'],['Stage','Ready']],true,now);
11
+ assert.equal(result.count,1);assert.deepEqual(result.items,[{id:'A',identity:meta.identity}]);assert.equal(result.eligible,true);
12
+ assert.equal(selectWork([],['Executor'],[['Executor','RoleX']],false,now).eligible,false);
13
+ assert.throws(()=>selectWork(all,['Executor'],[['Missing','x']],false,now),/unavailable/);
14
+ assert.throws(()=>selectWork([{...all[0],fieldValues:{...all[0].fieldValues,pageInfo:{hasNextPage:true}}}],['Executor'],[],false,now),/Incomplete/);
15
+ });
16
+ test('provider errors never turn into an empty-success response',async()=>{
17
+ await assert.rejects(()=>checkProject('PVT_test',[],false,async()=>({stdout:JSON.stringify({errors:[{message:'denied'}]})})),/unavailable/);
18
+ await assert.rejects(()=>checkProject('wrong',[],false),/node ID/);
19
+ });
20
+
21
+ test('coordination observes all states without treating them as queue assignments',()=>{
22
+ const future=item('future','RoleX','Backlog',{schemaVersion:1,identity:'x',notBefore:'2030-01-01T00:00:00Z'});
23
+ const closed={...item('closed'),isArchived:true,content:{state:'CLOSED',body:'```ez-work\ninvalid\n```'}};
24
+ const result=selectWork([future,closed],['Executor','Stage'],[],false,now,true);
25
+ assert.equal(result.count,2);assert.equal(result.eligible,true);
26
+ const changed=selectWork([{...future,updatedAt:'2026-10-07T11:59:00Z'},closed],['Executor','Stage'],[],false,now,true);
27
+ assert.notEqual(result.fingerprint,changed.fingerprint);
28
+ assert.equal(selectWork([],[],[],false,now,true).eligible,true);
29
+ assert.throws(()=>selectWork([],['Executor'],[['Executor','x']],false,now,true),/cannot filter/);
30
+ });
31
+
32
+ test('filtered fields must be single-select or text and readable',()=>{
33
+ const fields=[{name:'Executor',dataType:'SINGLE_SELECT'},{name:'Stage',dataType:'TEXT'},{name:'Points',dataType:'NUMBER'}];
34
+ assert.equal(selectWork([item('A')],fields,[['Executor','RoleX'],['Stage','Ready']],false,now).count,1);
35
+ assert.throws(()=>selectWork([item('A')],fields,[['Points','3']],false,now),/single-select or text/);
36
+ const bad=item('B');bad.fieldValues.nodes[0]={field:{name:'Executor'}};
37
+ assert.throws(()=>selectWork([bad],fields,[['Executor','RoleX']],false,now),/Unreadable value/);
38
+ assert.equal(selectWork([bad],fields,[['Stage','Ready']],false,now).count,1);
39
+ });
40
+ test('over-long or malformed task identity blocks the queue',()=>{
41
+ const long=item('A','RoleX','Ready',{schemaVersion:1,identity:'x'.repeat(201)});
42
+ assert.throws(()=>selectWork([long],['Executor'],[],false,now),/Invalid task metadata/);
43
+ const ok=item('B','RoleX','Ready',{schemaVersion:1,identity:'x'.repeat(200)});
44
+ assert.equal(selectWork([ok],['Executor'],[],false,now).items[0].identity.length,200);
45
+ const malformed=item('C');malformed.content.body='```ez-work\nnot json\n```';
46
+ assert.throws(()=>selectWork([item('D'),malformed],['Executor'],[],false,now));
47
+ });
48
+ test('checkProject follows every items page and rejects bad cursors',async()=>{
49
+ const page=(nodes,hasNextPage,endCursor)=>({stdout:JSON.stringify({data:{node:{fields:{nodes:[{name:'Executor',dataType:'SINGLE_SELECT'},{name:'Stage',dataType:'SINGLE_SELECT'}],pageInfo:{hasNextPage:false}},items:{nodes,pageInfo:{hasNextPage,endCursor}}}}})});
50
+ const calls=[];
51
+ const run=async(cmd,args)=>{calls.push(args);return args.includes('after=c1')?page([item('B')],false,null):page([item('A')],true,'c1');};
52
+ const result=await checkProject('PVT_test',[['Executor','RoleX']],false,run);
53
+ assert.equal(result.count,2);assert.equal(calls.length,2);assert.ok(!calls[0].some(a=>a.startsWith('after=')));
54
+ await assert.rejects(()=>checkProject('PVT_test',[],false,async()=>page([item('A')],true,null)),/cursor/);
55
+ await assert.rejects(()=>checkProject('PVT_test',[],false,async()=>page([item('A'),item('A')],false,null)),/Repeated/);
56
+ await assert.rejects(()=>checkProject('PVT_test',[['Stage','Ready'],['Missing','x']],false,async()=>page([item('A')],false,null)),/unavailable/);
57
+ });
58
+ test('cli --help exits 0 and a bad project exits 1 with a message',()=>{
59
+ const help=spawnSync(process.execPath,['bin/work-check.mjs','--help'],{encoding:'utf8'});
60
+ assert.equal(help.status,0);assert.match(help.stdout,/ez github-work/);assert.match(help.stdout,/fail closed/);
61
+ const bad=spawnSync(process.execPath,['bin/work-check.mjs','--project','nope'],{encoding:'utf8'});
62
+ assert.equal(bad.status,1);assert.match(bad.stderr,/node ID/);assert.equal(bad.stdout,'');
63
+ });