@ramon-sg/issue-flow 0.3.3 → 0.3.4

package/README.md

@@ -119,7 +119,7 @@ Lo propio de cada repo (instalar, armar la base, levantar Docker) son **pasos**
 ```
 
 - **Cuándo corren:** `issue start` corre el `setup` en cada worktree nuevo, después de copiar `.worktreeinclude`. El hook `session` lo corre al abrir Claude en un worktree. El `teardown` corre antes de borrar un worktree, con `prune` o al limpiar después del merge.
-- **De dónde salen:** siempre de la config del checkout principal, nunca de la del worktree. Así una rama no puede sumar comandos a su propio setup. En la nube no hay otro checkout: ahí la config es la de la rama de la sesión.
+- **De dónde salen:** del `.agents/flow.json` de `origin/<base>`, nunca del worktree. Así una rama no puede sumar comandos a su propio setup, y un checkout principal que quedó atrás no deja al worktree sin su `install`. Si los pasos del checkout principal son otros, `issue-flow` lo avisa. Sin `origin/<base>`, o si ahí el archivo no es válido, usa los del checkout principal. Sin pasos, `worktree setup` e `issue start` dicen de qué archivo los leyeron. En la nube no hay otro checkout: ahí la config es la de la rama de la sesión. El teardown sigue usando la config del checkout principal.
 - **Pueden correr más de una vez:** `issue start` y el hook `session` corren el `setup` del mismo worktree, así que un paso sin `once` tiene que poder repetirse.
 - **`trusted`:** el paso corre solo si el código del worktree está en `origin/<base>` y no tiene cambios. Es para un install, que corre los scripts de `package.json` de esa rama. En la nube corre siempre, porque la máquina es descartable.
 - **`once`:** el paso no se repite una vez que funcionó (deja una marca en el git dir del worktree).

package/dist/commands/adapter.js

@@ -22,11 +22,11 @@ import { canonicalPath, dockerCleanup } from "../docker.js";
 import { checkoutRoot, currentBranch, locateRepo } from "../git.js";
 import { issueOfBranch } from "../issue-text.js";
 import { inPath } from "../launch.js";
-import { UsageError, warn } from "../output.js";
+import { warn } from "../output.js";
 import { releasePortClaims } from "../ports.js";
 import { copyWorktreeIncludes } from "../start-place.js";
 import { StartError } from "../start-state.js";
-import { runSetup, teardownWorktree } from "../worktree-steps.js";
+import { checkOnly, runSetup, teardownWorktree } from "../worktree-steps.js";
 import { issueStart } from "./issue-start.js";
 import { stepPlace } from "./worktree.js";
 /** Orca's CLI, which knows which issue a workspace came from; `ISSUE_FLOW_ORCA_CLI` changes it. */
@@ -162,9 +162,7 @@ function linkedPlace(options, out) {
  * @example await adapterSetup(options, out)
  */
 export async function adapterSetup(options, out) {
-    const names = options.config.worktrees.setup.map((step) => step.name);
-    if (options.only !== null && !names.includes(options.only))
-        throw new UsageError(`--only expects a setup step of .agents/flow.json (${names.join(", ") || "it has none"}): ${options.only}`);
+    checkOnly(stepPlace(options, out), options.only);
     const place = linkedPlace(options, out);
     if (place === null)
         return 0;

package/dist/commands/claude-hooks.js

@@ -111,7 +111,7 @@ export async function worktreeCreate(input, config, cwd, out) {
             throw new StartError(`could not make the worktree ${path}: ${add.err}`);
         copyWorktreeIncludes(mainRoot, path, stderrOnly);
     }
-    await runSetup({ root: path, mainRoot, base, config, out: stderrOnly, remote: false }, null);
+    await runSetup({ root: path, mainRoot, base, config, out: stderrOnly, remote: false }, null, true);
     out.stdout(`${path}\n`);
     return 0;
 }

package/dist/commands/session.js

@@ -90,7 +90,7 @@ export async function session(options, out) {
     if (remote)
         cloudSession(root, say);
     if (root !== mainRoot || remote)
-        await runSetup(place, null);
+        await runSetup(place, null, true);
     const unstarted = !remote && root !== mainRoot ? unstartedIssue(root) : null;
     if (unstarted !== null)
         say(`issue #${unstarted} was not started: its branch is not published and has no draft PR. Before working, run the start-issue skill (${unstarted}).`);

package/dist/commands/worktree.js

@@ -12,11 +12,11 @@ import { resolve } from "node:path";
 import { canonicalPath, dockerCleanup } from "../docker.js";
 import { checkoutRoot, git, isClean, locateRepo, safeToDelete, worktrees } from "../git.js";
 import { forgetSession } from "../launch.js";
-import { UsageError, warn } from "../output.js";
+import { warn } from "../output.js";
 import { claimPortBase, nextPortBase, portBase } from "../ports.js";
 import { isStale, LOCK_REASON } from "../session-lock.js";
 import { StartError } from "../start-state.js";
-import { runSetup, teardownWorktree } from "../worktree-steps.js";
+import { checkOnly, runSetup, teardownWorktree } from "../worktree-steps.js";
 /** The reason `claude --worktree` locks the worktrees it makes while its session lives. */
 const CLAUDE_LOCK_REASON = "claude session";
 /**
@@ -57,10 +57,9 @@ export function stepPlace(options, out) {
  * @example await worktreeSetup(options, out)
  */
 export async function worktreeSetup(options, out) {
-    const names = options.config.worktrees.setup.map((step) => step.name);
-    if (options.only !== null && !names.includes(options.only))
-        throw new UsageError(`--only expects a setup step of .agents/flow.json (${names.join(", ") || "it has none"}): ${options.only}`);
-    return (await runSetup(stepPlace(options, out), options.only)) ? 0 : 1;
+    const place = stepPlace(options, out);
+    checkOnly(place, options.only);
+    return (await runSetup(place, options.only)) ? 0 : 1;
 }
 /**
  * `worktree teardown [--path <dir>]`: cleans a worktree before deleting it (its steps, its

package/dist/worktree-steps.d.ts

@@ -1,5 +1,6 @@
-import type { FlowConfig } from "./config.js";
+import { type FlowConfig } from "./config.js";
 import { type Output } from "./output.js";
+import { type Step } from "./worktree-config.js";
 /** Folder, in the worktree's git dir, with a mark per `once` step that worked. */
 export declare const SETUP_MARKS_DIR = "issue-flow-setup";
 /** Where the steps run, and with what. */
@@ -30,17 +31,43 @@ export declare function trustedCode(root: string, base: string): boolean;
  * @example stepEnv(place, 21430).ISSUE_FLOW_PORT_BASE // "21430"
  */
 export declare function stepEnv(place: StepPlace, port: number | null): Record<string, string>;
+/** The setup steps a worktree runs, and where they were read. */
+export interface SetupSteps {
+    steps: Step[];
+    source: string;
+    warning: string | null;
+}
+/**
+ * The setup steps: those of `.agents/flow.json` in `origin/<base>`, which a worktree made
+ * from it has; none if the file is not there. In a cloud session, without `origin/<base>`,
+ * or with a file there that is not valid, those of the checkout's config. The warning says
+ * when the main checkout's steps differ, or why they were used.
+ * @param place - Where.
+ * @returns The steps, where they come from and a warning, or null.
+ * @example setupSteps(place).source // "origin/main:.agents/flow.json"
+ */
+export declare function setupSteps(place: StepPlace): SetupSteps;
+/**
+ * Checks that `--only` names one of the setup steps.
+ * @param place - Where.
+ * @param only - The step, or null.
+ * @throws UsageError if it names no step.
+ * @example checkOnly(place, "deps")
+ */
+export declare function checkOnly(place: StepPlace, only: string | null): void;
 /**
  * Prepares a worktree with the setup steps: one (`only`) or all, in order. In the main
  * checkout it does nothing, except in a cloud session, whose checkout is not a worktree. It
  * fixes the block of ports first, so the steps (and the apps after them) agree on it.
- * Never stops on a failed step: it says what to run and goes on.
+ * Never stops on a failed step: it says what to run and goes on. Without steps it says so,
+ * unless `quiet` (the session hooks, which run at every start).
  * @param place - Where.
  * @param only - The step to run, or null for all.
+ * @param quiet - True to say nothing when there are no steps.
  * @returns True if every step that ran worked.
  * @example await runSetup(place, null)
  */
-export declare function runSetup(place: StepPlace, only: string | null): Promise<boolean>;
+export declare function runSetup(place: StepPlace, only: string | null, quiet?: boolean): Promise<boolean>;
 /**
  * Cleans a worktree before it is deleted: its apps and then its teardown steps (if the
  * folder still exists), so a step that drops a database finds nobody connected; then its

package/dist/worktree-steps.js

@@ -1,7 +1,9 @@
 /**
  * @file Runs the steps of `worktrees.setup` and `worktrees.teardown` in a worktree. The
- * steps come from the main checkout's config, not the worktree's, so a branch cannot add
- * commands to its own setup. A `trusted` step (an install, which runs the lifecycle scripts
+ * setup steps come from `.agents/flow.json` in `origin/<base>`, not from the worktree, so a
+ * branch cannot add commands to its own setup, and a main checkout nobody pulled does not
+ * leave a new worktree without its install. The teardown steps come from the main
+ * checkout's config. A `trusted` step (an install, which runs the lifecycle scripts
  * of `package.json`) runs only if the worktree's code is in `origin/<base>` and has no
  * changes; a `once` step leaves a mark when it works and is not repeated. Two setups of one
  * worktree at a time (the tool's and the session hook's) take turns with a lock. Each step
@@ -12,11 +14,14 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
+import { CONFIG_PATH, isObject } from "./config-base.js";
+import { DEFAULT_CONFIG } from "./config.js";
 import { dockerCleanup, sanitizeLabel } from "./docker.js";
 import { git, isClean } from "./git.js";
-import { warn } from "./output.js";
+import { UsageError, warn } from "./output.js";
 import { claimPortBase, portBase, releasePortClaims, sha256 } from "./ports.js";
 import { stopApps } from "./stop-apps.js";
+import { worktreesSection } from "./worktree-config.js";
 /** Folder, in the worktree's git dir, with a mark per `once` step that worked. */
 export const SETUP_MARKS_DIR = "issue-flow-setup";
 /** The lock of the setup, in the worktree's git dir. */
@@ -78,6 +83,58 @@ function runStep(place, step, env) {
     warn(place.out, `step "${step.name}" failed${result.status === null ? "" : ` (exit ${result.status})`}; run '${step.run}' in ${place.root}.`);
     return false;
 }
+/**
+ * The setup steps: those of `.agents/flow.json` in `origin/<base>`, which a worktree made
+ * from it has; none if the file is not there. In a cloud session, without `origin/<base>`,
+ * or with a file there that is not valid, those of the checkout's config. The warning says
+ * when the main checkout's steps differ, or why they were used.
+ * @param place - Where.
+ * @returns The steps, where they come from and a warning, or null.
+ * @example setupSteps(place).source // "origin/main:.agents/flow.json"
+ */
+export function setupSteps(place) {
+    const local = place.config.worktrees.setup;
+    const ref = `origin/${place.base}`;
+    const fallback = { steps: local, source: `the main checkout's ${CONFIG_PATH}` };
+    // NOTE: a cloud session has no other checkout: its steps are those of the session's branch.
+    if (place.remote || !git(place.mainRoot, ["rev-parse", "-q", "--verify", `${ref}^{commit}`]).ok)
+        return { ...fallback, warning: null };
+    const source = `${ref}:${CONFIG_PATH}`;
+    const shown = git(place.mainRoot, ["show", source]);
+    let steps;
+    try {
+        if (!shown.ok)
+            steps = DEFAULT_CONFIG.worktrees.setup;
+        else {
+            const raw = JSON.parse(shown.out);
+            steps = worktreesSection(isObject(raw) ? raw.worktrees : undefined, DEFAULT_CONFIG.worktrees).setup;
+        }
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { ...fallback, warning: `${source} is not valid: ${reason}; using the main checkout's steps.` };
+    }
+    const differ = JSON.stringify(steps) !== JSON.stringify(local);
+    return {
+        steps,
+        source,
+        warning: differ ? `the setup steps come from ${source}; the main checkout's differ (is it behind? pull it).` : null,
+    };
+}
+/**
+ * Checks that `--only` names one of the setup steps.
+ * @param place - Where.
+ * @param only - The step, or null.
+ * @throws UsageError if it names no step.
+ * @example checkOnly(place, "deps")
+ */
+export function checkOnly(place, only) {
+    if (only === null)
+        return;
+    const names = setupSteps(place).steps.map((step) => step.name);
+    if (!names.includes(only))
+        throw new UsageError(`--only expects a setup step of ${CONFIG_PATH} (${names.join(", ") || "it has none"}): ${only}`);
+}
 /**
  * Takes the setup's lock: a folder with the pid. A lock of a process that is gone is taken
  * over, and so is one without a pid that is some seconds old (its process died before
@@ -126,17 +183,24 @@ function alive(pid) {
  * Prepares a worktree with the setup steps: one (`only`) or all, in order. In the main
  * checkout it does nothing, except in a cloud session, whose checkout is not a worktree. It
  * fixes the block of ports first, so the steps (and the apps after them) agree on it.
- * Never stops on a failed step: it says what to run and goes on.
+ * Never stops on a failed step: it says what to run and goes on. Without steps it says so,
+ * unless `quiet` (the session hooks, which run at every start).
  * @param place - Where.
  * @param only - The step to run, or null for all.
+ * @param quiet - True to say nothing when there are no steps.
  * @returns True if every step that ran worked.
  * @example await runSetup(place, null)
  */
-export async function runSetup(place, only) {
+export async function runSetup(place, only, quiet = false) {
     const { root, mainRoot, config, out } = place;
     if (root === mainRoot && !place.remote)
         return true;
-    const chosen = config.worktrees.setup.filter((step) => only === null || step.name === only);
+    const found = setupSteps(place);
+    if (found.warning !== null)
+        warn(out, found.warning);
+    if (found.steps.length === 0 && !quiet)
+        warn(out, `no setup steps in ${found.source}; nothing ran.`);
+    const chosen = found.steps.filter((step) => only === null || step.name === only);
     const ports = config.worktrees.ports;
     const port = ports === null ? null : await claimPortBase(ports, root, null);
     if (ports !== null && port === null)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramon-sg/issue-flow",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Issue-to-PR workflow for any repo: names each issue's branch, creates its worktree, opens the draft PR and launches Claude Code, locally and in Claude's cloud.",
   "license": "MIT",
   "type": "module",

package/schema.json

@@ -76,7 +76,7 @@
           "default": ".claude/worktrees"
         },
         "setup": {
-          "description": "Steps that prepare a worktree, in order. They come from the main checkout's config, never the worktree's.",
+          "description": "Steps that prepare a worktree, in order. They come from this file in origin/<base> (the main checkout's if origin has none to read), never the worktree's.",
           "type": "array",
           "items": {
             "type": "object",