ekohacks 0.6.0 → 0.8.0

package/README.md

@@ -12,6 +12,8 @@ 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. 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
 
 - A tested core policy behind nullable infrastructure, in the style of [James Shore's Testing Without Mocks](https://www.jamesshore.com/v2/projects/nullables): real wrappers around `git`, `gh` and `npm`, each with a `createNull()` that answers with configurable responses and records what was asked of it. No mocks, no spies.

package/dist/cli.js

@@ -7,6 +7,7 @@ import { dirname } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { GhWrapper } from './infrastructure/gh.js';
 import { GitWrapper } from './infrastructure/git.js';
+import { LinearWrapper } from './infrastructure/linear.js';
 import { NpmWrapper } from './infrastructure/npm.js';
 import { ProcessRunner } from './infrastructure/process.js';
 import { ClaudeWrapper } from './infrastructure/claude.js';
@@ -15,11 +16,15 @@ 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, 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 archive <team> <column> [--yes]',
+    '       ekohacks stories create <team> <backlog.json> [--yes] [--dry-run]',
 ].join('\n');
 const FLAGS = ['--yes', '--dry-run'];
 const argv = process.argv.slice(2);
@@ -31,6 +36,13 @@ const printChecks = (checks) => {
         console.log(check.passed ? `  ok    ${check.name}` : `  FAIL  ${check.name}: ${check.reason}`);
     }
 };
+const confirm = async (question) => {
+    const readline = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await readline.question(`${question} (y/n) `);
+    readline.close();
+    return answer.trim().toLowerCase() === 'y';
+};
+const narrate = (line) => console.log(`  ${line}`);
 if (command === 'docs') {
     const subject = rest[0];
     if (rest.length !== 1 || (subject !== 'check' && subject !== 'sync' && subject !== 'draft')) {
@@ -140,6 +152,106 @@ if (command === 'docs') {
     printChecks(report.checks);
     process.exit(report.checks.every((check) => check.passed) ? 0 : 1);
 }
+if (command === 'stories') {
+    const subject = rest[0];
+    const team = rest[1];
+    const target = rest[2];
+    const shapeOk = team !== undefined &&
+        ((subject === 'fetch' && rest.length <= 4) ||
+            (target !== undefined &&
+                ((subject === 'archive' && rest.length === 3) ||
+                    (subject === 'create' && rest.length === 3))));
+    if (!shapeOk) {
+        console.error(USAGE);
+        process.exit(2);
+    }
+    if (process.env.LINEAR_API_KEY === undefined || process.env.LINEAR_API_KEY === '') {
+        console.error(`stopped: stories ${subject} needs LINEAR_API_KEY`);
+        process.exit(1);
+    }
+    const linear = LinearWrapper.create();
+    const approve = yes ? () => Promise.resolve(true) : confirm;
+    try {
+        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 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(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,
+                column: target,
+                linear,
+                confirm: approve,
+                narrate,
+            });
+            if ('stopped' in result) {
+                console.error(`stopped: ${result.stopped}`);
+                process.exit(1);
+            }
+            process.exit(0);
+        }
+        if (!existsSync(target)) {
+            console.error(`stopped: no ${target} in this directory`);
+            process.exit(1);
+        }
+        let backlog;
+        try {
+            const parsed = JSON.parse(readFileSync(target, 'utf8'));
+            if (!Array.isArray(parsed)) {
+                throw new Error('not a list');
+            }
+            backlog = parsed;
+        }
+        catch {
+            console.error(`stopped: ${target} is not a JSON list of stories`);
+            process.exit(1);
+        }
+        const result = await storiesCreate({
+            team,
+            backlog,
+            linear,
+            confirm: approve,
+            narrate,
+            dryRun,
+        });
+        if ('stopped' in result) {
+            console.error(`stopped: ${result.stopped}`);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`stopped: ${error.message}`);
+        process.exit(1);
+    }
+}
 const first = rest[0];
 const subcommand = first === 'preflight' || first === 'cut' || first === 'ship' ? first : undefined;
 const version = subcommand === undefined ? first : rest[1];
@@ -157,13 +269,6 @@ const read = (file) => readFileSync(file, 'utf8');
 const changelog = read('CHANGELOG.md');
 const manifest = JSON.parse(read('package.json'));
 const pkg = manifest.name;
-const confirm = async (question) => {
-    const readline = createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await readline.question(`${question} (y/n) `);
-    readline.close();
-    return answer.trim().toLowerCase() === 'y';
-};
-const narrate = (line) => console.log(`  ${line}`);
 if (subcommand === undefined) {
     const result = await release({
         version,

package/dist/infrastructure/linear.js

@@ -0,0 +1,222 @@
+const API = 'https://api.linear.app/graphql';
+const STORIES_PAGE = `query StoriesPage($team: String!, $column: String!, $after: String) {
+  issues(
+    filter: { team: { key: { eq: $team } }, state: { name: { eq: $column } } }
+    first: 100
+    after: $after
+    orderBy: updatedAt
+  ) {
+    pageInfo { hasNextPage endCursor }
+    nodes { identifier title description completedAt estimate labels { nodes { name } } }
+  }
+}`;
+// No cursor here on purpose: archived stories drop out of default query results, so the
+// archive loop re-fetches this first page until it comes back empty.
+const STORY_IDS = `query StoryIds($team: String!, $column: String!) {
+  issues(
+    filter: { team: { key: { eq: $team } }, state: { name: { eq: $column } } }
+    first: 100
+  ) {
+    nodes { id identifier }
+  }
+}`;
+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 } }
+}`;
+// Wraps the Linear surface the stories commands need, behind the one GraphQL endpoint.
+// Real and null share every line above the bottom layer: create() posts to api.linear.app
+// with the key from the environment, createNull() answers GraphQL-shaped envelopes from
+// configured state and never opens a socket; the real side is proven against a real board
+// rather than a faked Linear. idRounds configures successive answers to storyIds(): each
+// call takes the next round and the last round repeats, so a test can walk a column down
+// to empty. archiveRounds configures how many archives succeed per call; beyond the list,
+// all of them do.
+export class LinearWrapper {
+    static create({ apiKey = process.env.LINEAR_API_KEY ?? '', } = {}) {
+        return new LinearWrapper(async (body) => {
+            const response = await fetch(API, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Authorization: apiKey },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                throw new Error(`linear answered ${response.status}: ${await response.text()}`);
+            }
+            return (await response.json());
+        });
+    }
+    static createNull({ pages = [[]], board = [[]], idRounds = [[]], archiveRounds = [], teams = {}, } = {}) {
+        let idRound = 0;
+        let archiveRound = 0;
+        let minted = 0;
+        return new LinearWrapper((body) => {
+            const answer = (data) => Promise.resolve({ data });
+            if (body.query.includes('issueCreate')) {
+                minted += 1;
+                const issue = {
+                    id: `null-issue-${minted}`,
+                    identifier: `NULL-${minted}`,
+                    url: `https://linear.app/nulled/issue/NULL-${minted}`,
+                };
+                return answer({ issueCreate: { issue } });
+            }
+            if (body.query.includes('issueArchive')) {
+                const calls = body.query.match(/issueArchive/g) ?? [];
+                const index = archiveRound;
+                archiveRound += 1;
+                const successes = archiveRounds[index] ?? calls.length;
+                return answer(Object.fromEntries(calls.map((_, i) => [`a${i}`, { success: i < successes }])));
+            }
+            if (body.query.includes('teams(')) {
+                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;
+                const index = after === null ? 0 : Number(after.replace('cursor-', ''));
+                const hasNextPage = index < pages.length - 1;
+                return answer({
+                    issues: {
+                        pageInfo: { hasNextPage, endCursor: hasNextPage ? `cursor-${index + 1}` : null },
+                        nodes: (pages[index] ?? []).map((story) => ({
+                            ...story,
+                            labels: { nodes: story.labels.map((name) => ({ name })) },
+                        })),
+                    },
+                });
+            }
+            const round = Math.min(idRound, idRounds.length - 1);
+            idRound += 1;
+            return answer({ issues: { nodes: idRounds[round] ?? [] } });
+        });
+    }
+    post;
+    constructor(post) {
+        this.post = post;
+    }
+    async query(query, variables) {
+        const envelope = await this.post({ query, variables });
+        if (envelope.errors !== undefined && envelope.errors.length > 0) {
+            throw new Error(`linear answered: ${envelope.errors.map((error) => error.message).join('; ')}`);
+        }
+        return envelope.data;
+    }
+    async storiesPage({ team, column, after, }) {
+        const data = (await this.query(STORIES_PAGE, { team, column, after: after ?? null }));
+        const stories = data.issues.nodes.map((node) => ({
+            identifier: node.identifier,
+            title: node.title,
+            description: node.description,
+            completedAt: node.completedAt,
+            estimate: node.estimate,
+            labels: node.labels.nodes.map((label) => label.name),
+        }));
+        const { hasNextPage, endCursor } = data.issues.pageInfo;
+        return hasNextPage && endCursor !== null ? { stories, nextCursor: endCursor } : { stories };
+    }
+    async storyIds({ team, column }) {
+        const data = (await this.query(STORY_IDS, { team, column }));
+        return data.issues.nodes;
+    }
+    archiveTrackers = [];
+    trackArchives() {
+        const tracker = [];
+        this.archiveTrackers.push(tracker);
+        return { data: tracker };
+    }
+    // Aliases let one request carry many issueArchive calls — a0, a1, a2 and so on — so a
+    // page of a hundred costs four requests instead of a hundred. The ids interpolated into
+    // the mutation are UUIDs the API itself answered, never user input.
+    async archive(ids) {
+        if (ids.length === 0) {
+            return 0;
+        }
+        const calls = ids.map((id, index) => `a${index}: issueArchive(id: ${JSON.stringify(id)}) { success }`);
+        const data = (await this.query(`mutation { ${calls.join(' ')} }`));
+        for (const tracker of this.archiveTrackers) {
+            tracker.push(ids);
+        }
+        return Object.values(data).filter((entry) => entry.success).length;
+    }
+    // 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() {
+        const tracker = [];
+        this.createTrackers.push(tracker);
+        return { data: tracker };
+    }
+    async createStory(options) {
+        const input = { teamId: options.teamId, title: options.title };
+        if (options.description !== undefined) {
+            input.description = options.description;
+        }
+        if (options.parentId !== undefined) {
+            input.parentId = options.parentId;
+        }
+        const data = (await this.query(CREATE_STORY, { input }));
+        for (const tracker of this.createTrackers) {
+            tracker.push(options);
+        }
+        return data.issueCreate.issue;
+    }
+}

package/dist/logic/stories.js

@@ -0,0 +1,149 @@
+const issueNumber = (identifier) => Number(identifier.split('-')[1]);
+// 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) {
+        const result = await linear.storiesPage({ team, column, after });
+        narrate(`page ${page}: ${result.stories.length} stories`);
+        stories.push(...result.stories);
+        if (result.nextCursor === undefined) {
+            break;
+        }
+        after = result.nextCursor;
+    }
+    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}`);
+        return { archived: 0 };
+    }
+    // A full first page hides the true count behind the cursor, so the question says so.
+    const count = refs.length === 100 ? '100 or more' : String(refs.length);
+    if (!(await confirm(`archive ${count} stories from ${team}/${column}?`))) {
+        return { stopped: 'archive not approved' };
+    }
+    let archived = 0;
+    while (refs.length > 0) {
+        for (let start = 0; start < refs.length; start += batchSize) {
+            const chunk = refs.slice(start, start + batchSize);
+            const successes = await linear.archive(chunk.map((ref) => ref.id));
+            if (successes !== chunk.length) {
+                return { stopped: `archive fell short: ${successes} of ${chunk.length} in one request` };
+            }
+            archived += successes;
+            narrate(`archived ${archived} so far`);
+        }
+        refs = await linear.storyIds({ team, column });
+    }
+    narrate(`${archived} stories archived from ${team}/${column}`);
+    return { archived };
+};
+const countStories = (backlog) => backlog.reduce((sum, story) => sum + 1 + countStories(story.children ?? []), 0);
+const hasUntitled = (backlog) => backlog.some((story) => typeof story.title !== 'string' ||
+    story.title.trim() === '' ||
+    hasUntitled(story.children ?? []));
+// A new project's backlog as a file: stories nest to any depth, and each one is created
+// before its children so the children can carry its id as parentId. --dry-run narrates the
+// would-have tree and never touches the board; the real run confirms with the full count.
+export const storiesCreate = async ({ team, backlog, linear, confirm, narrate, dryRun = false, }) => {
+    const count = countStories(backlog);
+    if (count === 0) {
+        return { stopped: 'the backlog carries no stories' };
+    }
+    if (hasUntitled(backlog)) {
+        return { stopped: 'a backlog story has no title' };
+    }
+    if (dryRun) {
+        const preview = (stories, depth) => {
+            for (const story of stories) {
+                narrate(`${'  '.repeat(depth)}would have created ${story.title}`);
+                preview(story.children ?? [], depth + 1);
+            }
+        };
+        preview(backlog, 0);
+        narrate(`would have created ${count} stories in ${team}`);
+        return { created: 0 };
+    }
+    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' };
+    }
+    let created = 0;
+    const create = async (stories, parentId, depth) => {
+        for (const story of stories) {
+            const card = await linear.createStory({
+                teamId,
+                title: story.title,
+                ...(story.description === undefined ? {} : { description: story.description }),
+                ...(parentId === undefined ? {} : { parentId }),
+            });
+            created += 1;
+            narrate(`${'  '.repeat(depth)}created ${card.identifier} ${story.title}`);
+            await create(story.children ?? [], card.id, depth + 1);
+        }
+    };
+    await create(backlog, undefined, 0);
+    return { created };
+};

package/package.json

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