@ramon-sg/issue-flow 0.0.0-stage → 0.1.0

package/dist/commands/init.js

@@ -0,0 +1,213 @@
+/**
+ * @file `issue-flow init`: sets a repo up for the flow, and can run again to fill in what
+ * is missing. It writes `.agents/flow.json` (from `paseo.json` if the repo has one, plus the
+ * recipes it picks), the flow's dev dependencies and scripts in `package.json`, and the
+ * `SessionStart`, `WorktreeCreate` and `WorktreeRemove` hooks. Then, each after asking, it
+ * runs `claude-cloud init`, installs `claude-repo-guard` with what the flow needs in its
+ * options, and opens the skills menu of `skills-manager` with the two catalogs (`init` if
+ * the repo has no manifest, `add` if it has one, because `init` stops then). A tool that
+ * fails is reported and the rest goes on.
+ */
+import { confirm } from "../ask.js";
+import { CONFIG_PATH, isObject } from "../config-base.js";
+import { parseConfig } from "../config.js";
+import { checkoutRoot, locateRepo } from "../git.js";
+import { guardOptions } from "../guard-config.js";
+import { UsageError, warn } from "../output.js";
+import { withFlowPackages } from "../package-edits.js";
+import { applyRecipe, detectedRecipes, loadRecipes, projectPrefix } from "../recipes.js";
+import { registerHooks } from "../settings-hooks.js";
+import { CLOUD_SPEC, FLOW_CATALOG, GENERAL_CATALOG, GUARD_CONFIG, GUARD_SPEC, ownVersions, packageManager, readJson, runNpx, SETTINGS_FILE, SetupError, SKILLS_MANIFEST, writeJson, } from "../setup-files.js";
+/** The skills picked without a terminal: the flow's, and the audit `close-pr` uses. */
+const DEFAULT_SKILLS = [
+    ...["github-issues", "start-issue", "close-pr", "pr-review-comments", "pr-worktree"].map((name) => `catalog:${FLOW_CATALOG}/${name}`),
+    `catalog:${GENERAL_CATALOG}/code-audit`,
+];
+/**
+ * The URL of the config's schema at a version.
+ * @param version - This package's version.
+ * @returns The URL.
+ * @example schemaUrl("0.1.0") // "https://raw.githubusercontent.com/ramon-sg/issue-flow/v0.1.0/schema.json"
+ */
+export function schemaUrl(version) {
+    return `https://raw.githubusercontent.com/${FLOW_CATALOG}/v${version}/schema.json`;
+}
+/**
+ * A new config: the schema, and the branch rules of `paseo.json` if the repo has one.
+ * @param root - The repo.
+ * @param version - This package's version.
+ * @returns The config and what it took from `paseo.json`.
+ */
+function freshConfig(root, version) {
+    const raw = { $schema: schemaUrl(version) };
+    const issues = readJson(root, "paseo.json")?.project;
+    const paseo = isObject(issues) && isObject(issues.issues) ? issues.issues : null;
+    if (paseo === null)
+        return { raw, changes: ["new"] };
+    const branch = {};
+    if (typeof paseo.branchTemplate === "string")
+        branch.template = paseo.branchTemplate;
+    if (isObject(paseo.types))
+        branch.types = paseo.types;
+    if (Object.keys(branch).length > 0)
+        raw.branch = branch;
+    return { raw, changes: ["new, with the branch rules of paseo.json"] };
+}
+/**
+ * The recipes to apply: the ones named with `--recipe`, or each one the repo's files
+ * suggest, after asking (all of them with `--yes`).
+ * @param root - The repo.
+ * @param options - The options.
+ * @param out - Where to ask.
+ * @returns The recipes.
+ * @throws UsageError if `--recipe` names one that does not exist.
+ */
+async function pickRecipes(root, options, out) {
+    const recipes = loadRecipes();
+    if (options.recipes !== null) {
+        const unknown = options.recipes.find((name) => !recipes.some((recipe) => recipe.name === name));
+        if (unknown !== undefined)
+            throw new UsageError(`unknown recipe ${unknown}; there are ${recipes.map((recipe) => recipe.name).join(", ")}.`);
+        return recipes.filter((recipe) => options.recipes?.includes(recipe.name));
+    }
+    const picked = [];
+    for (const recipe of recipes.filter((item) => detectedRecipes(root, recipes).includes(item.name)))
+        if (options.yes || (await confirm(out, `Recipe ${recipe.name}: ${recipe.description} Add it?`)))
+            picked.push(recipe);
+    return picked;
+}
+/** How a line of a change that keeps what the repo had starts. */
+const KEPT = "kept ";
+/**
+ * What `init` would write: the config, `package.json` and the settings' hooks.
+ * @param root - The repo.
+ * @param versions - This package's versions.
+ * @param recipes - The recipes to apply.
+ * @returns The files that change.
+ * @throws ConfigError if the resulting config is invalid; SetupError if a file is broken.
+ */
+function plan(root, versions, recipes) {
+    const existing = readJson(root, CONFIG_PATH);
+    const start = existing === null ? freshConfig(root, versions.issueFlow) : { raw: existing, changes: [] };
+    let { raw } = start;
+    const configChanges = [...start.changes];
+    for (const recipe of recipes) {
+        const applied = applyRecipe(raw, recipe, projectPrefix(root));
+        raw = applied.raw;
+        configChanges.push(...applied.changes.map((change) => (change.startsWith(KEPT) ? `${change} (${recipe.name})` : `${recipe.name}: ${change}`)));
+    }
+    parseConfig(raw);
+    const pkg = withFlowPackages(readJson(root, "package.json"), versions, false);
+    const hooks = registerHooks(readJson(root, SETTINGS_FILE), versions.issueFlow);
+    const file = (path, value, lines) => ({
+        path,
+        value,
+        changes: lines.filter((line) => !line.startsWith(KEPT)).map((line) => `${path}: ${line}`),
+        kept: lines.filter((line) => line.startsWith(KEPT)).map((line) => `${path}: ${line}`),
+    });
+    return [file(CONFIG_PATH, raw, configChanges), file("package.json", pkg.pkg, pkg.changes), file(SETTINGS_FILE, hooks.settings, hooks.changes)];
+}
+/**
+ * Runs one of the other tools after asking, and says if it failed.
+ * @param step - What it is and how it runs.
+ * @param options - The options.
+ * @param out - Where to ask and write.
+ * @returns False if it ran and failed.
+ */
+async function external(step, options, out) {
+    if (!options.yes && !(await confirm(out, step.question)))
+        return true;
+    if (step.run())
+        return true;
+    warn(out, step.failed);
+    return false;
+}
+/**
+ * Installs `claude-repo-guard`, after writing in its options what the flow needs.
+ * @param root - The repo.
+ * @param out - Where to write.
+ * @returns Whether it installed.
+ */
+function installGuard(root, out) {
+    const flow = readJson(root, CONFIG_PATH);
+    const baseBranch = typeof flow?.baseBranch === "string" ? flow.baseBranch : null;
+    const { options, changes } = guardOptions(readJson(root, GUARD_CONFIG), baseBranch, process.platform);
+    if (changes.length > 0)
+        writeJson(root, GUARD_CONFIG, options);
+    for (const change of changes)
+        out.stdout(`  ${change}\n`);
+    return runNpx(root, [GUARD_SPEC, "install", "--yes"]);
+}
+/**
+ * The ids of the default skills the manifest does not take yet: `skills-manager` leaves the
+ * ones it has out of the candidates, and fails if `--select` names one.
+ * @param manifest - The skills manifest, or null.
+ * @returns The ids to pick.
+ */
+function missingDefaults(manifest) {
+    const sources = Array.isArray(manifest?.sources) ? manifest.sources.filter(isObject) : [];
+    const taken = new Set(sources.flatMap((source) => (typeof source.catalog === "string" && Array.isArray(source.skills) ? source.skills.map((name) => `catalog:${String(source.catalog)}/${String(name)}`) : [])));
+    return DEFAULT_SKILLS.filter((id) => !taken.has(id));
+}
+/**
+ * Opens the skills menu with the flow's catalog, at this version, and the general one; without
+ * a terminal or with `--yes`, it picks the flow's skills and `code-audit` that are not there yet.
+ * @param root - The repo.
+ * @param versions - This package's versions.
+ * @param pick - Whether to pick without the menu.
+ * @param out - Where to say there is nothing to add.
+ * @returns Whether `skills-manager` worked, or true if there was nothing to pick.
+ */
+function installSkills(root, versions, pick, out) {
+    const manifest = readJson(root, SKILLS_MANIFEST);
+    const command = manifest === null ? "init" : "add";
+    const args = [`@ramon-sg/skills-manager@${versions.skillsManager}`, command, "--catalog", `${FLOW_CATALOG}#v${versions.issueFlow}`, "--catalog", GENERAL_CATALOG];
+    if (!pick)
+        return runNpx(root, args);
+    const missing = missingDefaults(manifest);
+    if (missing.length === 0) {
+        out.stdout(`The flow's skills and code-audit are already in ${SKILLS_MANIFEST}.\n`);
+        return true;
+    }
+    return runNpx(root, [...args, "--select", missing.join(",")]);
+}
+/**
+ * Sets the repo up for the flow; see the file's header.
+ * @param options - The options.
+ * @param out - Where to write and ask.
+ * @returns 0, or 1 if a file was not written or another tool failed.
+ * @throws SetupError outside the main checkout or with a broken file; ConfigError if the
+ * config would be invalid; UsageError for an unknown recipe.
+ * @example await init({ cwd, yes: true, recipes: null, skills: true, guard: true, cloud: true }, out)
+ */
+export async function init(options, out) {
+    const located = locateRepo(options.cwd);
+    if (located === null)
+        throw new SetupError("run init inside a checkout of the repo.");
+    if (checkoutRoot(options.cwd) !== located.mainRoot)
+        throw new SetupError(`run init in the main checkout, ${located.mainRoot}, not in a worktree.`);
+    const root = located.mainRoot;
+    const versions = ownVersions();
+    const files = plan(root, versions, await pickRecipes(root, options, out)).filter((file) => file.changes.length > 0 || file.kept.length > 0);
+    for (const line of files.flatMap((file) => file.kept))
+        warn(out, line);
+    const lines = files.flatMap((file) => file.changes);
+    if (lines.length === 0)
+        out.stdout("The config, package.json and the hooks are already set up.\n");
+    else
+        out.stdout(`issue-flow ${versions.issueFlow} will write:\n${lines.map((line) => `  ${line}\n`).join("")}`);
+    if (lines.length > 0 && !options.yes && !(await confirm(out, "Write it?"))) {
+        warn(out, "nothing written.");
+        return 1;
+    }
+    for (const file of files.filter((item) => item.changes.length > 0))
+        writeJson(root, file.path, file.value);
+    const results = [
+        !options.cloud || await external({ question: "Set up Claude cloud sessions with claude-cloud init?", run: () => runNpx(root, [CLOUD_SPEC, "init"]), failed: `claude-cloud init failed; run 'npx ${CLOUD_SPEC} init' to retry.` }, options, out),
+        !options.guard || await external({ question: "Install claude-repo-guard (auto mode, with the sandbox)?", run: () => installGuard(root, out), failed: `claude-repo-guard did not install; run 'npx ${GUARD_SPEC} install' to retry.` }, options, out),
+        !options.skills || await external({ question: "Pick the skills now?", run: () => installSkills(root, versions, options.yes || !out.interactive, out), failed: "skills-manager failed; run issue-flow init again to retry." }, options, out),
+    ];
+    const manager = packageManager(root, readJson(root, "package.json"));
+    out.stdout(`Next: run '${manager} install', and commit .agents/, .claude/ and package.json.\n`);
+    return results.every(Boolean) ? 0 : 1;
+}

package/dist/commands/issue-branch.d.ts

@@ -0,0 +1,36 @@
+import type { FlowConfig, Namer } from "../config.js";
+import { type Output } from "../output.js";
+/** Issues `--missing` proposes at most when no `--limit` is given. */
+export declare const MISSING_LIMIT = 100;
+/** Options of `issue branch`. */
+export interface BranchOptions {
+    repo: string;
+    config: FlowConfig;
+    cwd: string;
+    namer?: Namer;
+    json: boolean;
+    limit?: number;
+    yes: boolean;
+    dryRun: boolean;
+}
+/**
+ * `issue branch <n>...`: the branch of each issue, without writing anything.
+ * @param numbers - The issues.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The exit code: 1 if an issue does not exist.
+ * @throws GitHubError if GitHub fails.
+ */
+export declare function branchOf(numbers: number[], options: BranchOptions, out: Output): Promise<number>;
+/**
+ * `issue branch --missing`: proposes the branch of every open issue without a block, new
+ * or old, in one Claude call, and adds the slug block after confirming. Only the slug is
+ * written, so a type Claude would pick is not used: the branch shown is the one the issue
+ * will give, and an issue without a type gets a warning if the template uses `{type}`. A failed edit does not stop the
+ * others.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The exit code: 1 if an edit failed.
+ * @throws GitHubError if the issues cannot be listed.
+ */
+export declare function branchMissing(options: BranchOptions, out: Output): Promise<number>;

package/dist/commands/issue-branch.js

@@ -0,0 +1,182 @@
+/**
+ * @file `issue-flow issue branch`: proposes the branch of some issues, or with `--missing`
+ * of every open issue without a branch block, and adds a "Slug de rama" block to those
+ * only after a confirmation (`--yes`, or answering in the terminal).
+ */
+import { createInterface } from "node:readline/promises";
+import { editIssue, listIssues, viewIssue } from "@ramon-sg/github-rest";
+import { hasBranchBlock, SLUG_HEADING, withSlugBlock } from "../branch-name.js";
+import { proposeBranches } from "../propose.js";
+import { emitJson, UsageError, warn } from "../output.js";
+/** Issues `--missing` proposes at most when no `--limit` is given. */
+export const MISSING_LIMIT = 100;
+/**
+ * An issue of github-rest as what `proposeBranches` reads.
+ * @param issue - The issue.
+ * @returns Number, title, body and label names.
+ */
+function info(issue) {
+    return {
+        number: issue.number,
+        title: issue.title,
+        body: issue.body,
+        labels: issue.labels.map(({ name }) => name),
+    };
+}
+/**
+ * Prints the proposals: as JSON, or one line each (`#42 fix/42-cart (claude)`).
+ * @param proposals - The proposals.
+ * @param out - Where to write.
+ * @param json - Whether to print JSON.
+ */
+function print(proposals, out, json) {
+    if (json)
+        return emitJson(out, proposals);
+    for (const proposal of proposals)
+        out.stdout(`#${proposal.number} ${proposal.branch} (${proposal.source})\n`);
+}
+/**
+ * `issue branch <n>...`: the branch of each issue, without writing anything.
+ * @param numbers - The issues.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The exit code: 1 if an issue does not exist.
+ * @throws GitHubError if GitHub fails.
+ */
+export async function branchOf(numbers, options, out) {
+    const issues = [];
+    let code = 0;
+    for (const number of numbers) {
+        const found = await viewIssue(options.repo, number);
+        if (found === null) {
+            warn(out, `issue #${number} does not exist in ${options.repo}.`);
+            code = 1;
+            continue;
+        }
+        issues.push(info(found));
+    }
+    const { proposals, warnings } = proposeBranches(issues, options.config, {
+        cwd: options.cwd,
+        ...(options.namer === undefined ? {} : { namer: options.namer }),
+    });
+    for (const line of [...warnings, ...proposals.flatMap((proposal) => proposal.warnings)])
+        warn(out, line);
+    print(proposals, out, options.json);
+    return code;
+}
+/**
+ * Asks in the terminal whether to write the blocks.
+ * @param count - How many issues.
+ * @returns True if the answer is yes.
+ */
+async function confirm(count) {
+    const prompt = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await prompt.question(`Add the "Slug de rama" block to ${count} issue(s)? [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
+/**
+ * Whether the blocks may be written: `--yes`, or a yes in the terminal. Never with
+ * `--dry-run`, and never without a terminal and without `--yes`.
+ * @param options - The options.
+ * @param count - How many issues.
+ * @param out - Where to write.
+ * @returns True if they may be written.
+ */
+async function mayWrite(options, count, out) {
+    if (options.dryRun)
+        return false;
+    if (options.yes)
+        return true;
+    if (!out.interactive) {
+        warn(out, "nothing written: pass --yes to add the blocks.");
+        return false;
+    }
+    return confirm(count);
+}
+/**
+ * Adds the block to one issue, from a copy read right before writing: Claude and the
+ * question can take minutes, and an edit made meanwhile must not be lost. If the issue got
+ * a block in the meantime, it is left alone.
+ * @param repo - `owner/repo`.
+ * @param proposal - The issue and its branch.
+ * @returns Whether the block was added (false if the issue already had one or is gone).
+ * @throws GitHubError if GitHub fails.
+ */
+async function addBlock(repo, proposal) {
+    const fresh = await viewIssue(repo, proposal.number);
+    if (fresh === null || hasBranchBlock(fresh.body))
+        return false;
+    await editIssue(repo, proposal.number, { body: withSlugBlock(fresh.body, proposal.slug) });
+    return true;
+}
+/**
+ * The open issues without a block, new or old. GitHub can only skip one heading, so the
+ * pages are read without a limit (up to github-rest's page ceiling) and both are filtered
+ * here; otherwise issues with the old block would use up the limit and leave out, without
+ * a warning, issues that have none.
+ * @param options - The options (repo and limit).
+ * @param out - Where to warn that the list was cut short.
+ * @returns The issues, at most the limit.
+ * @throws GitHubError if the issues cannot be listed.
+ */
+async function missingIssues(options, out) {
+    const listed = await listIssues(options.repo, {
+        missingHeading: SLUG_HEADING,
+        limit: Number.POSITIVE_INFINITY,
+    });
+    const limit = options.limit ?? MISSING_LIMIT;
+    const issues = listed.issues.filter((issue) => !hasBranchBlock(issue.body));
+    if (listed.truncated || issues.length > limit)
+        warn(out, "GitHub has more issues than were read; run it again after this.");
+    return issues.slice(0, limit);
+}
+/**
+ * `issue branch --missing`: proposes the branch of every open issue without a block, new
+ * or old, in one Claude call, and adds the slug block after confirming. Only the slug is
+ * written, so a type Claude would pick is not used: the branch shown is the one the issue
+ * will give, and an issue without a type gets a warning if the template uses `{type}`. A failed edit does not stop the
+ * others.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The exit code: 1 if an edit failed.
+ * @throws GitHubError if the issues cannot be listed.
+ */
+export async function branchMissing(options, out) {
+    if (options.json && !options.dryRun && !options.yes)
+        throw new UsageError("--missing --json needs --dry-run or --yes: there is no terminal to confirm in.");
+    const issues = await missingIssues(options, out);
+    const { proposals, warnings } = proposeBranches(issues.map(info), options.config, {
+        cwd: options.cwd,
+        claudeType: false,
+        ...(options.namer === undefined ? {} : { namer: options.namer }),
+    });
+    const untyped = proposals
+        .filter((proposal) => proposal.type === null && options.config.branch.template.includes("{type}"))
+        .map((proposal) => `#${proposal.number}: it has no type label, so its branch has no type until it gets one.`);
+    for (const line of [...warnings, ...proposals.flatMap((proposal) => proposal.warnings), ...untyped])
+        warn(out, line);
+    print(proposals, out, options.json);
+    if (proposals.length === 0 || !(await mayWrite(options, proposals.length, out)))
+        return 0;
+    let code = 0;
+    for (const proposal of proposals) {
+        try {
+            if (!(await addBlock(options.repo, proposal))) {
+                warn(out, `#${proposal.number}: it got a branch block or was deleted meanwhile; left alone.`);
+                continue;
+            }
+            if (!options.json)
+                out.stdout(`#${proposal.number}: block added.\n`);
+        }
+        catch (error) {
+            warn(out, `#${proposal.number}: ${error instanceof Error ? error.message : String(error)}`);
+            code = 1;
+        }
+    }
+    return code;
+}

package/dist/commands/issue-start.d.ts

@@ -0,0 +1,11 @@
+import { type Output } from "../output.js";
+import { type StartOptions } from "../start-state.js";
+/**
+ * `issue start <n>`.
+ * @param options - The options.
+ * @param out - Where to write.
+ * @returns The exit code.
+ * @throws StartError if something stops the start; GitHubError if GitHub fails.
+ * @example await issueStart(options, processOutput())
+ */
+export declare function issueStart(options: StartOptions, out: Output): Promise<number>;