@idea1/cli 1.8.2 → 1.9.0

package/dist/workflow/engine/ship-flow.js

@@ -0,0 +1,221 @@
+import { logger } from '../../lib/logger.js';
+import { claudeEntryPointOption } from '../../lib/claude-options.js';
+import { isolationModeOption, resolveIsolationMode } from '../../lib/isolation.js';
+import * as git from '../../services/git.js';
+import * as github from '../../services/github.js';
+import * as worktree from '../../services/worktree.js';
+import { WorkflowBranchState } from '../data/workflow-context.js';
+import { WorkflowStates } from '../data/workflow-states.js';
+import { mergeConfirmationOption } from './approval-flow.js';
+import { branchCreationOptions } from './branch-setup.js';
+import { reviewersOption } from './handlers/ready-for-approval.js';
+import { advanceAsNeededTo, requireLiveContext, startWorkflowManagementAtCommit } from './workflow-engine.js';
+/**
+ * Shipping work that exists before its project item's branch does. Uncommitted changes in a
+ * checkout of the branch an item's branch is cut from (the base branch, `working/release` by
+ * default) are carried onto the item's branch: committed and pushed there, never on the base
+ * branch, and checked out per the isolation mode. The item can then be advanced through every
+ * workflow state up to Approved and Merged with nothing asked on the way: no Claude session is
+ * started, the PR is opened and assigned to the person running the command (who, by merging it, is
+ * the approver of record), and it merges once the required checks pass - the same gate as every
+ * other stage-1 merge.
+ *
+ * Changes are carried only onto a branch with no work of its own: one created for them, or a live
+ * branch that still matches the branch it is cut from.
+ */
+export const carryLocalChangesOption = {
+    longName: 'carry-local-changes',
+    shortName: 'c',
+    description: 'Commit and push the uncommitted changes of your base branch checkout on the item\'s branch rather than the base branch (only while the item\'s branch has no commits of its own)',
+    isFlag: true
+};
+export const approveAndMergeOption = {
+    longName: 'approve-and-merge',
+    description: 'Advance the item through every workflow state up to Approved and Merged without prompting: open its PR assigned to you, wait for the required checks and merge it',
+    isFlag: true
+};
+/**
+ * Whether the resolved options carry local changes. Reads a flag, so options that depend on it are
+ * declared after `carryLocalChangesOption`.
+ */
+export function carriesLocalChanges(resolved) {
+    return resolved[carryLocalChangesOption.longName] === 'true';
+}
+/**
+ * Whether the resolved options approve and merge the item's PR.
+ */
+export function approvesAndMerges(resolved) {
+    return resolved[approveAndMergeOption.longName] === 'true';
+}
+/**
+ * The branch creation options alongside carrying: carried changes go onto an independent branch,
+ * so the workflow type is asked only when nothing is carried.
+ */
+export const branchCreationOptionsWithCarrying = branchCreationOptions.map(option => option.longName === 'workflow-type'
+    ? { ...option, dependsOn: (resolved) => !carriesLocalChanges(resolved) }
+    : option);
+export const commitMessageOption = {
+    longName: 'commit-message',
+    shortName: 'M',
+    description: 'Commit message for the carried changes (default: the new item\'s title)',
+    defaultValue: '',
+    promptWhenDefaultExists: false
+};
+/**
+ * Reviewers requested on the PR when the item is approved and merged. Never asked: the PR's
+ * assignee approves it.
+ */
+export const unpromptedReviewersOption = { ...reviewersOption, dependsOn: () => false };
+/**
+ * The options that apply once changes are carried or the item is approved and merged. Declared
+ * after the two flags, which they depend on.
+ */
+export const shipOptions = [
+    { ...commitMessageOption, dependsOn: carriesLocalChanges },
+    {
+        ...isolationModeOption,
+        dependsOn: resolved => carriesLocalChanges(resolved) || approvesAndMerges(resolved)
+    },
+    unpromptedReviewersOption
+];
+/**
+ * The uncommitted changes of the current checkout, to carry onto an item's branch; null when there
+ * are none. Read before anything is created, so a checkout the changes cannot be carried from stops
+ * the command before an item or branch exists. `expectedSourceBranch` is the branch a new item's
+ * branch will be cut from, or null when an existing item decides that, which carrying checks.
+ *
+ * The checkout's own branch must have no commits that origin lacks: carrying takes uncommitted
+ * changes only, and such commits would either travel with them or be left behind on the base branch.
+ */
+export async function findLocalChanges(expectedSourceBranch) {
+    if (!await git.hasUncommittedChanges()) {
+        return null;
+    }
+    const sourceBranch = await git.getCurrentBranch();
+    if (sourceBranch === 'HEAD') {
+        throw new Error('This checkout is not on a branch (detached HEAD), so there is no base branch to carry its uncommitted changes from.');
+    }
+    if (expectedSourceBranch && sourceBranch !== expectedSourceBranch) {
+        throw new Error(`Uncommitted changes are carried from a checkout of ${expectedSourceBranch}, the branch the item's branch is cut from; ` +
+            `this checkout is on ${sourceBranch}.`);
+    }
+    if (!await git.fetchRemoteBranch(sourceBranch)) {
+        throw new Error(`${sourceBranch} is not on origin, so the item's branch cannot be cut from it.`);
+    }
+    if (await git.hasCommitsNotIn('HEAD', `origin/${sourceBranch}`)) {
+        throw new Error(`Your ${sourceBranch} has commits that are not on origin. Only uncommitted changes are carried: ` +
+            `push those commits or move them off ${sourceBranch} first.`);
+    }
+    return { sourceBranch, checkoutPath: (await git.getRepoRoot()).trim() };
+}
+/**
+ * Carry uncommitted changes onto the item's branch. The changes are committed on top of the
+ * checkout's commit without touching the checkout, and the commit becomes the tip of the item's
+ * branch on origin: a new branch, recorded on the platform as the item's, for an item with no live
+ * branch, or the item's live branch while it has no commits of its own. The base branch is left as
+ * origin has it.
+ *
+ * The branch then gets its local checkout per the isolation mode. In the main repository, the
+ * checkout that held the changes switches to the branch with its working tree as it is, which is
+ * the branch's tip. Otherwise the branch gets a worktree, and the checkout that held the changes is
+ * cleaned of them, unless they changed meanwhile.
+ *
+ * Reads `commit-message`, `title`, `branch-name`, `base-branch` and `isolation` from the
+ * transition's options.
+ */
+export async function carryLocalChanges(transition, changes) {
+    const { sourceBranch, checkoutPath } = changes;
+    const options = transition.options;
+    process.chdir(checkoutPath);
+    logger.section(`Carry uncommitted changes from ${sourceBranch}`);
+    const context = transition.context;
+    if (context?.branchState === WorkflowBranchState.Merged) {
+        throw new Error(`The work of ${transition.projectItemUrl} is already merged (${context.branchName}); carry these changes onto a new item.`);
+    }
+    const liveContext = context?.branchState === WorkflowBranchState.Live ? context : null;
+    const expectedTipSha = liveContext ? await requireBranchWithNoCommitsOfItsOwn(liveContext, sourceBranch) : null;
+    if (!liveContext) {
+        const baseBranch = options['base-branch'] || await worktree.resolveBaseBranch();
+        if (sourceBranch !== baseBranch) {
+            throw new Error(`The item's branch is cut from ${baseBranch}, so changes are carried from a checkout of it; this checkout is on ${sourceBranch}.`);
+        }
+    }
+    const message = options['commit-message'] || options['title'] || `Changes carried from ${sourceBranch} for ${transition.projectItemUrl}`;
+    const treeSha = await git.writeWorkingTreeTree();
+    const commitSha = await git.commitTree(treeSha, 'HEAD', message);
+    if (liveContext) {
+        await git.pushCommitToBranch(liveContext.branchName, commitSha, expectedTipSha);
+    }
+    else {
+        await startWorkflowManagementAtCommit(transition, {
+            shortBranchName: options['branch-name'] || null,
+            baseBranch: sourceBranch,
+            commitSha
+        });
+    }
+    const { branchName } = requireLiveContext(transition);
+    if (resolveIsolationMode(options) === 'main-repo') {
+        await git.switchToCommitKeepingWorkingTree(branchName, commitSha);
+        transition.workingPath = checkoutPath;
+    }
+    else {
+        const { workingPath } = await worktree.ensureBranchEnvironment('worktree', branchName);
+        if (await git.writeWorkingTreeTree() === treeSha) {
+            await git.discardWorkingTreeChanges();
+            logger.dim(`Removed the carried changes from ${checkoutPath}, which stays on ${sourceBranch}`);
+        }
+        else {
+            logger.warning(`The changes in ${checkoutPath} changed while they were carried, so they were left there. Discard them once you have checked ${branchName}.`);
+        }
+        transition.workingPath = workingPath;
+        process.chdir(workingPath);
+    }
+    logger.success(`Carried the uncommitted changes onto ${branchName} (${commitSha.substring(0, 12)})`);
+    logger.hint(`Working directory: ${transition.workingPath}`);
+}
+/**
+ * The tip on origin of an item's live branch that changes can be carried onto: one cut from the
+ * branch the changes are carried from, with no checkout here (the checkout's own work would be
+ * stranded), and with no commits of its own, on origin or locally.
+ */
+async function requireBranchWithNoCommitsOfItsOwn(context, sourceBranch) {
+    const { branchName } = context;
+    const branchSource = context.stackBranch ?? context.baseBranch;
+    if (branchSource !== sourceBranch) {
+        throw new Error(`${branchName} is cut from ${branchSource}, so changes are carried onto it from a checkout of ${branchSource}; this checkout is on ${sourceBranch}.`);
+    }
+    const checkoutPath = await git.getCheckoutPathForBranch(branchName);
+    if (checkoutPath) {
+        throw new Error(`${branchName} is checked out at ${checkoutPath}. Changes are carried only onto a branch with no checkout: commit them there, or remove that checkout first.`);
+    }
+    if (!await git.fetchRemoteBranch(branchName)) {
+        throw new Error(`${branchName} is not on origin.`);
+    }
+    const hasOwnCommits = await git.hasCommitsNotIn(`origin/${branchName}`, `origin/${sourceBranch}`)
+        || (await git.localBranchExists(branchName) && await git.hasCommitsNotIn(branchName, `origin/${sourceBranch}`));
+    if (hasOwnCommits) {
+        throw new Error(`${branchName} already has commits of its own. Changes are carried only onto a branch that still matches ${sourceBranch}: ` +
+            `check ${branchName} out (idea1 join-project-item) and commit them there.`);
+    }
+    return git.resolveCommit(`origin/${branchName}`);
+}
+/**
+ * Advance the item through every workflow state up to Approved and Merged, asking nothing: the
+ * states on the way get the options a person would otherwise be asked for. No Claude session is
+ * started on the way through Agent Implementation, the PR is assigned to the person running the
+ * command, who merges it once the required checks pass (which brings the base branch's local
+ * checkout up to date with the merge). Each state runs its usual automation, so a run that stops -
+ * on failing checks, say - continues from where it stopped when run again.
+ */
+export async function approveAndMerge(transition) {
+    const login = await github.getCurrentLogin();
+    Object.assign(transition.options, {
+        [isolationModeOption.longName]: resolveIsolationMode(transition.options),
+        [claudeEntryPointOption.longName]: 'none',
+        assignee: login,
+        [reviewersOption.longName]: transition.options[reviewersOption.longName] ?? '',
+        [mergeConfirmationOption.longName]: 'true'
+    });
+    await advanceAsNeededTo(transition, WorkflowStates.ApprovedAndMerged);
+}
+//# sourceMappingURL=ship-flow.js.map

package/dist/workflow/engine/ship-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ship-flow.js","sourceRoot":"","sources":["../../../src/workflow/engine/ship-flow.ts"],"names":[],"mappings":"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"}

package/dist/workflow/engine/workflow-engine.d.ts

@@ -16,6 +16,12 @@ import { type WorkflowState } from '../data/workflow-states.js';
  * to any earlier state, recording the state only) finds its work done and leaves it as it is - also
  * once the work is merged and its branch retired.
  *
+ * A command names its target - a project item URL, a branch name or a GitHub PR URL - and the
+ * engine resolves it to a project item, or to a branch no item is recorded for (`resolveTarget`).
+ * Work happens where the branch is checked out when it has a local checkout; a branch with none is
+ * worked on through origin and GitHub, and is checked out only when a step needs its files
+ * (`ensureWorkingPath`), so a command never arranges a checkout itself.
+ *
  * A command resolves the transition it operates on and, when it changes the item, calls the
  * operation that says so: `advanceAsNeededTo` to move the item on, `reenterState` to run the
  * automation of the state it is already in. Both put the item under workflow management on the way
@@ -56,27 +62,76 @@ export interface WorkflowStateHandler {
     complete?: (transition: WorkflowTransition) => Promise<void>;
 }
 export interface ResolveTransitionInput {
-    /** Project item URL; required when the current branch is not the item's branch. */
-    projectItemUrl?: string;
+    /**
+     * What the command operates on: a project item URL, a branch name, or a GitHub PR URL (standing
+     * for its head branch). Null for the current branch.
+     */
+    target: string | null;
     /** Resolved command options, handed to the state handlers. */
     options: Record<string, string>;
 }
 /**
- * Work out which project item and branch a command operates on. Reading only: an item outside
- * workflow management resolves to a transition with no context, and the transition the command
- * goes on to make is what gives it one.
- *
- * On a managed branch (the platform records the current branch as an item's) the branch is the
- * target. Otherwise the item URL is required: its summary is read from the platform and, when its
- * branch is live and checked out somewhere locally, that checkout becomes the working directory.
+ * What a target resolves to: a project item, or a branch no project item is recorded for.
+ */
+export type ResolvedTarget = {
+    kind: 'item';
+    transition: WorkflowTransition;
+} | {
+    kind: 'branch';
+    branchName: string;
+};
+/**
+ * Work out which project item a command operates on, for commands that need one. A branch (named,
+ * behind a PR URL, or the current one) must be a project item's branch.
  */
 export declare function resolveTransition(input: ResolveTransitionInput): Promise<WorkflowTransition>;
 /**
- * Like `resolveTransition`, returning null for a current branch outside workflow management when
- * no item URL was given. For commands that also operate on a branch with no project item
- * (`ready-for-approval`, `approve-pr`).
+ * Work out what a command operates on: a project item, or a branch with no project item, for the
+ * commands that also take those (`ready-for-approval`, `approve-pr`). Reading only: an item outside
+ * workflow management resolves to a transition with no context, and the transition the command goes
+ * on to make is what gives it one.
+ *
+ * A branch is the target's when it is a project item's branch (the platform records it as the
+ * item's), so a branch or PR URL target names the item as surely as its URL does. Whatever the
+ * target, its branch's local checkout, when it has one, is brought up to date with origin and
+ * becomes the working directory; a branch with no checkout is worked on through origin and GitHub
+ * alone, and gets a checkout only when a step needs one (`ensureWorkingPath`).
+ */
+export declare function resolveTarget(input: ResolveTransitionInput): Promise<ResolvedTarget>;
+/** The target named by a run, with what is known of it before anything moves. See `readTarget`. */
+export interface TargetSummary {
+    /** The target as given: an item URL, a branch name or a PR URL. */
+    target: string;
+    /** What progress output calls the target: `#<id> <title>` for an item, the branch name otherwise. */
+    label: string;
+    /** The item's URL; null for a branch with no project item. */
+    projectItemUrl: string | null;
+    /** The branch carrying the work; null for an item with no live branch in this repository. */
+    branchName: string | null;
+    /** The item's state; null for an item outside workflow management or a branch with no item. */
+    currentState: WorkflowState | null;
+}
+/**
+ * What a target is - its item, branch and state - read without moving into any checkout or
+ * changing anything, so many targets can be checked before any of them is worked on.
  */
-export declare function resolveTransitionIfManaged(input: ResolveTransitionInput): Promise<WorkflowTransition | null>;
+export declare function readTarget(target: string): Promise<TargetSummary>;
+export interface StartWorkflowManagementAtCommitInput {
+    /** The branch name under the branch prefix; null to derive one from the item. */
+    shortBranchName: string | null;
+    /** The branch the new branch is cut from and its pull request targets. */
+    baseBranch: string;
+    /** The new branch's tip: a commit on top of `baseBranch`. */
+    commitSha: string;
+}
+/**
+ * Put an item that has no live branch under workflow management on a new independent branch whose
+ * tip is a commit already made on top of the base branch - for work that exists before its branch
+ * does - rather than on the base branch's tip. Recorded on the platform as `advanceAsNeededTo`
+ * records a branch it creates: a new context enters the first state, an existing one keeps its
+ * status. Work that was merged has no branch left to put new work on.
+ */
+export declare function startWorkflowManagementAtCommit(transition: WorkflowTransition, input: StartWorkflowManagementAtCommitInput): Promise<void>;
 /**
  * Move the item to `targetState` one state at a time: each state on the way is entered in order -
  * its handler prepares, the state is recorded on the item, its handler completes - exactly as
@@ -94,10 +149,17 @@ export declare function advanceAsNeededTo(transition: WorkflowTransition, target
  * the branch is recorded on the item alongside it.
  */
 export declare function reenterState(transition: WorkflowTransition, state: WorkflowState): Promise<void>;
+/**
+ * Prompt for every handler option that was not supplied on the command line and that advancing
+ * from `fromState` to `targetState` needs, so a handler reached through `next` asks the same
+ * questions as its dedicated command would. A batch asks this for each of its items, up front, so
+ * its unattended runs are asked nothing; an option answered once is not asked again.
+ */
+export declare function resolveOptionsForAdvancing(fromState: WorkflowState | null, targetState: WorkflowState, options: Record<string, string>): Promise<void>;
 /**
  * The summary of the project item a branch in this repository implements, with the item's workflow
- * context. Null for a branch outside workflow management. The item URL is remembered locally for
- * the branch.
+ * context. Null for a branch outside workflow management, which the base branch always is: no item
+ * is assigned to it, so it is not looked up. The item URL is remembered locally for the branch.
  */
 export declare function getProjectItemSummaryForBranch(branchName: string): Promise<ProjectItemSummary | null>;
 /**
@@ -163,6 +225,14 @@ export declare function isWorkMerged(transition: WorkflowTransition): boolean;
  * The item's context with its live branch, for handlers that do branch work.
  */
 export declare function requireLiveContext(transition: WorkflowTransition): WorkflowContext;
+/**
+ * The branch's local checkout, created when it has none - a step that needs to work in the branch's
+ * files asks for it, and only then does a checkout come to exist: a worktree, or the branch checked
+ * out in the main repository, per the `isolation` option. The checkout becomes the working
+ * directory. Steps that can work through origin and GitHub alone use `transition.workingPath`,
+ * the checkout the branch already had.
+ */
+export declare function ensureWorkingPath(transition: WorkflowTransition): Promise<string>;
 /**
  * The local checkout a handler needs, with guidance when there is none.
  */

package/dist/workflow/engine/workflow-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-engine.d.ts","sourceRoot":"","sources":["../../../src/workflow/engine/workflow-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflow-engine.d.ts","sourceRoot":"","sources":["../../../src/workflow/engine/workflow-engine.ts"],"names":[],"mappings":"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"}