ekohacks 0.7.0 → 0.8.0

package/README.md

@@ -12,7 +12,7 @@ The second command is `ekohacks docs check`, specified in [`stories/6-docs-check
 
 `ekohacks docs sync` is the other half, specified in [`stories/8-docs-sync.md`](stories/8-docs-sync.md): it writes the edits the check can prove — the entry-point block, the prose counts — and scaffolds a stub page for an entry point the docs just gained, leaving the prose to a person. [`stories/9-docs-draft.md`](stories/9-docs-draft.md) specifies drafting that prose and opening a PR for a human to review; it is written down, not built.
 
-The third command is `ekohacks stories`, specified in stories [11](stories/11-stories-fetch.md)–[13](stories/13-stories-create.md): the Linear board as a surface. `fetch` reads a whole column across pages, `archive` empties it once it has been read (reversible, batched, safe to re-run), and `create` pushes a new project's backlog from a JSON file with a `--dry-run` preview. It grew from the dojo's story-audit workshop scripts and the propi-o backlog push, and needs `LINEAR_API_KEY` in the environment.
+The third command is `ekohacks stories`, specified in stories [11](stories/11-stories-fetch.md)–[13](stories/13-stories-create.md): the Linear board as a surface. `fetch` reads a whole column across pages, `archive` empties it once it has been read (reversible, batched, safe to re-run), and `create` pushes a new project's backlog from a JSON file with a `--dry-run` preview. It grew from the dojo's story-audit workshop scripts and the propi-o backlog push, and needs `LINEAR_API_KEY` in the environment. A mistyped team or column is a named stop rather than an empty result, specified in [story 14](stories/14-stories-named-stops.md) after user testing hit the ambiguity twice in an hour, and `fetch` with just the team prints the whole board, column by column ([story 15](stories/15-stories-overview.md)).
 
 ## How this is built
 

package/dist/cli.js

@@ -16,13 +16,13 @@ import { docsCheck, docsDraft, docsSync, draftBranchConflict, draftPrompts, open
 import { preflight } from './logic/preflight.js';
 import { release } from './logic/release.js';
 import { ship } from './logic/ship.js';
-import { storiesArchive, storiesCreate, storiesFetch, storyLine, } from './logic/stories.js';
+import { storiesArchive, storiesCreate, storiesFetch, storiesOverview, storyLine, } from './logic/stories.js';
 const USAGE = [
     'usage: ekohacks release [preflight|cut|ship] <version> [--yes]',
     '       ekohacks docs check',
     '       ekohacks docs sync [--dry-run]',
     '       ekohacks docs draft [--yes]',
-    '       ekohacks stories fetch <team> <column> [out.json]',
+    '       ekohacks stories fetch <team> [<column> [out.json]]',
     '       ekohacks stories archive <team> <column> [--yes]',
     '       ekohacks stories create <team> <backlog.json> [--yes] [--dry-run]',
 ].join('\n');
@@ -157,10 +157,10 @@ if (command === 'stories') {
     const team = rest[1];
     const target = rest[2];
     const shapeOk = team !== undefined &&
-        target !== undefined &&
         ((subject === 'fetch' && rest.length <= 4) ||
-            (subject === 'archive' && rest.length === 3) ||
-            (subject === 'create' && rest.length === 3));
+            (target !== undefined &&
+                ((subject === 'archive' && rest.length === 3) ||
+                    (subject === 'create' && rest.length === 3))));
     if (!shapeOk) {
         console.error(USAGE);
         process.exit(2);
@@ -172,18 +172,37 @@ if (command === 'stories') {
     const linear = LinearWrapper.create();
     const approve = yes ? () => Promise.resolve(true) : confirm;
     try {
-        if (subject === 'fetch') {
+        if (subject === 'fetch' && target === undefined) {
+            const result = await storiesOverview({ team, linear, narrate });
+            if ('stopped' in result) {
+                console.error(`stopped: ${result.stopped}`);
+                process.exit(1);
+            }
+            for (const { column, count } of result.board) {
+                console.log(`${column}: ${count}`);
+            }
+            process.exit(0);
+        }
+        if (subject === 'fetch' && target !== undefined) {
             const out = rest[3];
-            const { stories } = await storiesFetch({ team, column: target, linear, narrate });
-            for (const story of stories) {
+            const result = await storiesFetch({ team, column: target, linear, narrate });
+            if ('stopped' in result) {
+                console.error(`stopped: ${result.stopped}`);
+                process.exit(1);
+            }
+            for (const story of result.stories) {
                 console.log(storyLine(story));
             }
             if (out !== undefined) {
-                writeFileSync(out, `${JSON.stringify(stories, null, 2)}\n`);
-                narrate(`${stories.length} stories written to ${out}`);
+                writeFileSync(out, `${JSON.stringify(result.stories, null, 2)}\n`);
+                narrate(`${result.stories.length} stories written to ${out}`);
             }
             process.exit(0);
         }
+        if (target === undefined) {
+            console.error(USAGE);
+            process.exit(2);
+        }
         if (subject === 'archive') {
             const result = await storiesArchive({
                 team,

package/dist/infrastructure/linear.js

@@ -20,8 +20,19 @@ const STORY_IDS = `query StoryIds($team: String!, $column: String!) {
     nodes { id identifier }
   }
 }`;
-const TEAM_ID = `query TeamId($key: String!) {
-  teams(filter: { key: { eq: $key } }) { nodes { id } }
+const TEAM = `query Team($key: String!) {
+  teams(filter: { key: { eq: $key } }) { nodes { id states { nodes { name position } } } }
+}`;
+const BOARD_PAGE = `query BoardPage($team: String!, $after: String) {
+  issues(
+    filter: { team: { key: { eq: $team } } }
+    first: 100
+    after: $after
+    orderBy: updatedAt
+  ) {
+    pageInfo { hasNextPage endCursor }
+    nodes { identifier state { name } }
+  }
 }`;
 const CREATE_STORY = `mutation CreateStory($input: IssueCreateInput!) {
   issueCreate(input: $input) { issue { id identifier url } }
@@ -48,7 +59,7 @@ export class LinearWrapper {
             return (await response.json());
         });
     }
-    static createNull({ pages = [[]], idRounds = [[]], archiveRounds = [], teams = {}, } = {}) {
+    static createNull({ pages = [[]], board = [[]], idRounds = [[]], archiveRounds = [], teams = {}, } = {}) {
         let idRound = 0;
         let archiveRound = 0;
         let minted = 0;
@@ -71,8 +82,35 @@ export class LinearWrapper {
                 return answer(Object.fromEntries(calls.map((_, i) => [`a${i}`, { success: i < successes }])));
             }
             if (body.query.includes('teams(')) {
-                const id = teams[body.variables?.key];
-                return answer({ teams: { nodes: id === undefined ? [] : [{ id }] } });
+                const team = teams[body.variables?.key];
+                return answer({
+                    teams: {
+                        nodes: team === undefined
+                            ? []
+                            : [
+                                {
+                                    id: team.id,
+                                    states: {
+                                        nodes: team.columns.map((name, position) => ({ name, position })),
+                                    },
+                                },
+                            ],
+                    },
+                });
+            }
+            if (body.query.includes('BoardPage')) {
+                const after = body.variables?.after;
+                const index = after === null ? 0 : Number(after.replace('cursor-', ''));
+                const hasNextPage = index < board.length - 1;
+                return answer({
+                    issues: {
+                        pageInfo: { hasNextPage, endCursor: hasNextPage ? `cursor-${index + 1}` : null },
+                        nodes: (board[index] ?? []).map((row) => ({
+                            identifier: row.identifier,
+                            state: { name: row.column },
+                        })),
+                    },
+                });
             }
             if (body.query.includes('pageInfo')) {
                 const after = body.variables?.after;
@@ -141,9 +179,25 @@ export class LinearWrapper {
         }
         return Object.values(data).filter((entry) => entry.success).length;
     }
-    async teamId(key) {
-        const data = (await this.query(TEAM_ID, { key }));
-        return data.teams.nodes[0]?.id;
+    // Columns come back in board order — the API answers states in an order of its own,
+    // position is the order the board shows.
+    async team(key) {
+        const data = (await this.query(TEAM, { key }));
+        const node = data.teams.nodes[0];
+        if (node === undefined) {
+            return undefined;
+        }
+        const states = [...node.states.nodes].sort((a, b) => a.position - b.position);
+        return { id: node.id, columns: states.map((state) => state.name) };
+    }
+    async boardPage({ team, after, }) {
+        const data = (await this.query(BOARD_PAGE, { team, after: after ?? null }));
+        const rows = data.issues.nodes.map((node) => ({
+            identifier: node.identifier,
+            column: node.state.name,
+        }));
+        const { hasNextPage, endCursor } = data.issues.pageInfo;
+        return hasNextPage && endCursor !== null ? { rows, nextCursor: endCursor } : { rows };
     }
     createTrackers = [];
     trackCreates() {

package/dist/logic/stories.js

@@ -1,9 +1,29 @@
 const issueNumber = (identifier) => Number(identifier.split('-')[1]);
-export const storyLine = (story) => `${story.identifier} [${story.labels.join(',')}] ${story.title}`;
+// A team or column that does not exist must stop by name, never read as an empty board:
+// user testing hit a typo'd column and a wrong-workspace key inside an hour, and both
+// answered silence. Team first — a wrong-workspace key is an unknown team from here —
+// then the column against the names the board actually has.
+const resolveColumn = async ({ team, column, linear, }) => {
+    const found = await linear.team(team);
+    if (found === undefined) {
+        return { stopped: `no team with key ${team}` };
+    }
+    if (!found.columns.includes(column)) {
+        return { stopped: `no column "${column}" in ${team} (it has: ${found.columns.join(', ')})` };
+    }
+    return undefined;
+};
+export const storyLine = (story) => story.labels.length === 0
+    ? `${story.identifier} ${story.title}`
+    : `${story.identifier} [${story.labels.join(',')}] ${story.title}`;
 // The read half of the workshop scripts as policy: pages of a hundred, the cursor from one
 // page becoming the after of the next, merged and sorted by issue number. Every page count
 // is narrated — reading page one and declaring victory is the classic mistake.
 export const storiesFetch = async ({ team, column, linear, narrate, }) => {
+    const stopped = await resolveColumn({ team, column, linear });
+    if (stopped !== undefined) {
+        return stopped;
+    }
     const stories = [];
     let after;
     for (let page = 1;; page += 1) {
@@ -18,11 +38,38 @@ export const storiesFetch = async ({ team, column, linear, narrate, }) => {
     stories.sort((a, b) => issueNumber(a.identifier) - issueNumber(b.identifier));
     return { stories };
 };
+// The board at a glance: one paginated walk of the whole team, counted locally, one row
+// per column in board order. The board's own columns seed the counts so an empty column
+// prints its zero — the point of an overview is the whole board, not the busy part.
+export const storiesOverview = async ({ team, linear, narrate, }) => {
+    const found = await linear.team(team);
+    if (found === undefined) {
+        return { stopped: `no team with key ${team}` };
+    }
+    const counts = new Map(found.columns.map((column) => [column, 0]));
+    let after;
+    for (let page = 1;; page += 1) {
+        const result = await linear.boardPage({ team, after });
+        narrate(`page ${page}: ${result.rows.length} stories`);
+        for (const row of result.rows) {
+            counts.set(row.column, (counts.get(row.column) ?? 0) + 1);
+        }
+        if (result.nextCursor === undefined) {
+            break;
+        }
+        after = result.nextCursor;
+    }
+    return { board: [...counts.entries()].map(([column, count]) => ({ column, count })) };
+};
 // The mutation half: batches of aliased issueArchive calls, re-fetching the first page of
 // the column until it comes back empty — archived stories drop out of default results, so
 // convergence is the loop condition and a re-run after a partial failure is safe. The one
 // human decision stays human: nothing is archived without the confirm answering yes.
 export const storiesArchive = async ({ team, column, linear, confirm, narrate, batchSize = 25, }) => {
+    const stopped = await resolveColumn({ team, column, linear });
+    if (stopped !== undefined) {
+        return stopped;
+    }
     let refs = await linear.storyIds({ team, column });
     if (refs.length === 0) {
         narrate(`nothing to archive in ${team}/${column}`);
@@ -75,10 +122,11 @@ export const storiesCreate = async ({ team, backlog, linear, confirm, narrate, d
         narrate(`would have created ${count} stories in ${team}`);
         return { created: 0 };
     }
-    const teamId = await linear.teamId(team);
-    if (teamId === undefined) {
+    const found = await linear.team(team);
+    if (found === undefined) {
         return { stopped: `no team with key ${team}` };
     }
+    const teamId = found.id;
     if (!(await confirm(`create ${count} stories in ${team}?`))) {
         return { stopped: 'create not approved' };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ekohacks",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The EkoHacks CLI: our everyday operations, automated one small command at a time.",
   "repository": {
     "type": "git",