@haystackeditor/cli 0.19.0 → 0.21.0

package/dist/commands/init.js

@@ -1,152 +1,399 @@
 /**
- * haystack init - Interactive setup wizard
+ * haystack init — set a repository up for `haystack verify` in one command.
  *
- * Creates .haystack.json with auto-detected settings.
+ * There is no setup file to write or keep current: the service works out how to
+ * run the app from what the repository already keeps working (APP-ONBOARDING-V1).
+ * init makes at most two small project-local changes, shows each as a diff
+ * before writing, and writes them only with consent (--yes, or yes at the prompt):
+ *   1. Claude Code's Stop hook, `haystack verify precompute --hook`, in the
+ *      per-developer .claude/settings.local.json (kept out of commits through
+ *      .git/info/exclude), when Claude Code is in use here;
+ *   2. a short marked block in AGENTS.md (and in CLAUDE.md when the repository
+ *      keeps one) telling coding agents to run `haystack verify` after a change.
+ * It then starts onboarding the app at the base `haystack verify` would use, so
+ * the app is usually ready by the first verify. Running it again changes only
+ * what is missing or out of date and shows where onboarding is.
+ *
+ * Exit codes: 0 set up (onboarding running or ready), 1 failed, 2 changes shown
+ * but not made (run with --yes), 3 onboarding blocked (the output says what
+ * would unblock it), 4 not logged in, 5 the Haystack GitHub App is not
+ * installed, 6 set up but onboarding stopped before finishing (run init again).
  */
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { detectProject } from '../utils/detect.js';
-import { parseRemoteUrl, UnsupportedRemoteUrlError } from '../utils/git.js';
-import { saveConfig, configExists } from '../utils/config.js';
-import { validateConfigSecurity, formatSecurityReport } from '../utils/secrets.js';
-export async function initCommand(options) {
-    console.log(chalk.cyan('\n🌾 Haystack Setup\n'));
-    // Check if config already exists
-    if (await configExists() && !options.force) {
-        console.log(chalk.yellow('.haystack.json already exists. Use --force to overwrite.\n'));
-        return;
+import { withSchema } from '../schema.js';
+import { NotLoggedInError, resolveAuthContext } from '../utils/auth.js';
+import { HAYSTACK_APP_INSTALL_URL, HaystackApiError, INSTALLATION_REQUIRED_CODE } from '../utils/haystack-api.js';
+import { findGitRoot } from '../utils/hooks.js';
+import { assertNoSymlinkOnPath } from '../utils/safe-write.js';
+import { CLAUDE_LOCAL_SETTINGS, CLAUDE_SHARED_SETTINGS, HAYSTACK_PRECOMPUTE_HOOK_COMMAND, claudeEntries, claudeSettingsPath, isCLIInstalled, isGitIgnored, isInstalledGlobally, isPrecomputeCommand, readClaudeSettings, } from './install-session-hooks.js';
+import { formatOnboarding, reportOnboardingState, startOnboarding } from './verify-onboarding.js';
+import { deriveBaseSha, EXPLICIT_WALL_MS, resolveOriginRepository } from './verify-precompute.js';
+const NOTE_BEGIN = '<!-- haystack:begin -->';
+const NOTE_END = '<!-- haystack:end -->';
+/** The agent instructions init keeps in AGENTS.md / CLAUDE.md, between its markers. */
+export const AGENT_NOTE = [
+    NOTE_BEGIN,
+    '## Haystack',
+    '',
+    'After you change this app\'s code, run `haystack verify` before you call the work done. It runs the app with and',
+    'without your change, explores it, and reports where the change shows up and what broke.',
+    '',
+    '- It often takes 10 to 15 minutes. If your command times out, run it again: it picks up the same crawl.',
+    '- Fix each bug it reports that your change caused, then run `haystack verify` again.',
+    '- If it says onboarding needs an answer, ask the user that question and file their choice with',
+    '  `haystack verify answer <question-id> <choice>`.',
+    '- `haystack verify --json` prints one JSON document; `haystack verify --help` explains the output and exit codes.',
+    '- If `haystack` is not installed, run each command as `npx -y @haystackeditor/cli@latest <command>`.',
+    NOTE_END,
+].join('\n');
+const EXIT_CODES = { planned: 2, 'login-required': 4, 'app-required': 5 };
+/** init's exit once set up: 0 onboarding running or ready, 3 blocked, 6 stopped before finishing. */
+function setUpExitCode(onboarding) {
+    if (onboarding.state === 'blocked')
+        return 3;
+    return onboarding.state === 'ready' || onboarding.state === 'onboarding' ? 0 : 6;
+}
+/* ------------------------------------------------------------------- plan */
+function isPlainFile(path) {
+    try {
+        return lstatSync(path).isFile();
     }
-    // Detect project
-    console.log(chalk.dim('Detecting project configuration...\n'));
-    const detected = await detectProject();
-    // Show what was detected
-    console.log(chalk.green('✓ Detected:'));
-    console.log(`  Package manager: ${chalk.bold(detected.packageManager)}`);
-    if (detected.framework) {
-        console.log(`  Framework: ${chalk.bold(detected.framework)}`);
-    }
-    if (detected.isMonorepo) {
-        console.log(`  Monorepo: ${chalk.bold(detected.monorepoTool || 'yes')}`);
-        if (detected.services?.length) {
-            console.log(`  Services: ${chalk.bold(detected.services.length)} packages detected`);
-        }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function isPlainDirectory(path) {
+    try {
+        return lstatSync(path).isDirectory();
     }
-    console.log('');
-    // Build config from detection (no interactive prompts)
-    const config = await buildConfigFromDetection(detected);
-    if (config.dev_server) {
-        console.log(`  Dev server: ${chalk.bold(config.dev_server.command)} (port ${config.dev_server.port})\n`);
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
     }
-    const configPath = await saveConfig(config);
-    console.log(chalk.green(`✓ Created ${configPath}`));
-    // Security validation
-    await runSecurityCheck(configPath);
-    console.log(chalk.green('\nDone! Run `haystack setup` to configure rules, signals, and policies.\n'));
 }
-/**
- * Run security check on config file
- */
-async function runSecurityCheck(configPath) {
-    const { safe, findings } = await validateConfigSecurity(configPath);
-    if (!safe) {
-        console.log(chalk.yellow('\n⚠️  Security Warning:\n'));
-        console.log(formatSecurityReport(findings));
-        console.log(chalk.yellow('Please remove hardcoded secrets before committing.\n'));
-    }
-    else if (findings.length > 0) {
-        console.log(chalk.dim('\n' + formatSecurityReport(findings)));
-    }
-}
-async function buildConfigFromDetection(detected) {
-    const env = {};
-    if (detected.suggestedAuthBypass) {
-        const [key, value] = detected.suggestedAuthBypass.split('=');
-        env[key] = value || 'true';
-    }
-    const pkgJson = await readPackageJson();
-    const name = resolveProjectName(pkgJson);
-    if (detected.isMonorepo && detected.services?.length) {
-        const services = {};
-        for (const s of detected.services) {
-            services[s.name] = {
-                ...(s.root !== './' ? { root: s.root } : {}),
-                command: s.suggestedCommand || 'pnpm dev',
-                ...(s.type === 'server' && s.suggestedPort ? { port: s.suggestedPort } : {}),
-                ...(s.type === 'batch' ? { type: 'batch' } : {}),
-                ready_pattern: 'ready|started|listening|Local:',
-                ...(Object.keys(env).length > 0 ? { env } : {}),
-                ...(s.suggestedDependsOn?.length ? { depends_on: s.suggestedDependsOn } : {}),
-            };
+function linesOf(text) {
+    return text === '' ? [] : text.replace(/\n$/, '').split('\n');
+}
+/** The lines `after` adds to or removes from `before` (`+`/`-`), with one line of
+ * context (` `) around each run of changes and `…` where unchanged lines are skipped. */
+export function lineDiff(before, after) {
+    const a = linesOf(before);
+    const b = linesOf(after);
+    let prefix = 0;
+    while (prefix < a.length && prefix < b.length && a[prefix] === b[prefix])
+        prefix += 1;
+    let suffix = 0;
+    while (suffix < a.length - prefix && suffix < b.length - prefix && a[a.length - 1 - suffix] === b[b.length - 1 - suffix])
+        suffix += 1;
+    const oldMiddle = a.slice(prefix, a.length - suffix);
+    const newMiddle = b.slice(prefix, b.length - suffix);
+    // Longest common subsequence of the differing middle; these are small files.
+    const lcs = Array.from({ length: oldMiddle.length + 1 }, () => new Array(newMiddle.length + 1).fill(0));
+    for (let i = oldMiddle.length - 1; i >= 0; i -= 1) {
+        for (let j = newMiddle.length - 1; j >= 0; j -= 1) {
+            lcs[i][j] = oldMiddle[i] === newMiddle[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
         }
-        return {
-            version: '1',
-            name,
-            services,
-        };
     }
-    const devServer = buildDevServer(detected, pkgJson?.scripts, env);
-    return {
-        version: '1',
-        name,
-        ...(devServer ? { dev_server: devServer } : {}),
-    };
-}
-/**
- * Prefer the GitHub repo name, then package.json name, then the directory
- * name. The directory basename alone is often a worktree or clone-dir name
- * that has nothing to do with the project.
- */
-function resolveProjectName(pkgJson) {
-    try {
-        return parseRemoteUrl().repo;
-    }
-    catch (err) {
-        // Classify by type, not message text (PR007). A remote that exists but
-        // isn't recognized deserves a warning — the fallback name may not match
-        // the repo. A missing remote/repo is normal for fresh projects.
-        if (err instanceof UnsupportedRemoteUrlError) {
-            console.log(chalk.yellow(`⚠ Git remote URL not recognized (${err.message}); using package.json/directory name instead`));
+    const ops = a.slice(0, prefix).map(line => ` ${line}`);
+    let i = 0;
+    let j = 0;
+    while (i < oldMiddle.length || j < newMiddle.length) {
+        if (i < oldMiddle.length && j < newMiddle.length && oldMiddle[i] === newMiddle[j]) {
+            ops.push(` ${oldMiddle[i]}`);
+            i += 1;
+            j += 1;
+        }
+        else if (j < newMiddle.length && (i === oldMiddle.length || lcs[i][j + 1] >= lcs[i + 1][j])) {
+            ops.push(`+${newMiddle[j]}`);
+            j += 1;
         }
         else {
-            console.log(chalk.dim('  No git remote found; using package.json/directory name'));
+            ops.push(`-${oldMiddle[i]}`);
+            i += 1;
         }
     }
-    return pkgJson?.name || path.basename(process.cwd());
+    ops.push(...a.slice(a.length - suffix).map(line => ` ${line}`));
+    const changed = (k) => ops[k] !== undefined && ops[k][0] !== ' ';
+    const shown = [];
+    for (let k = 0; k < ops.length; k += 1) {
+        if (changed(k) || changed(k - 1) || changed(k + 1))
+            shown.push(ops[k]);
+        else if (shown.length > 0 && shown[shown.length - 1] !== '…')
+            shown.push('…');
+    }
+    if (shown[shown.length - 1] === '…')
+        shown.pop();
+    return shown;
 }
-/**
- * Build a dev_server block for single-repo projects, but only when there is
- * real evidence of one: a dev/start script in package.json. Without that
- * gate we'd fabricate commands like `npm dev` that don't exist.
- */
-function buildDevServer(detected, scripts, env) {
-    const script = scripts?.dev ? 'dev' : scripts?.start ? 'start' : null;
-    if (!script)
-        return undefined;
-    const pm = detected.packageManager;
-    // npm and bun need the `run` form; pnpm/yarn run scripts directly.
-    const command = pm === 'npm' || pm === 'bun' ? `${pm} run ${script}` : `${pm} ${script}`;
+function change(gitRoot, target, reason, content) {
+    const before = existsSync(target) ? readFileSync(target, 'utf8') : null;
+    if (before === content)
+        return null;
+    const inside = relative(gitRoot, target);
     return {
-        command,
-        port: detected.suggestedPort || 3000,
-        ready_pattern: detected.suggestedReadyPattern || 'ready|started|listening|Local:',
-        ...(Object.keys(env).length > 0 ? { env } : {}),
+        path: inside.startsWith('..') || isAbsolute(inside) ? target : inside,
+        action: before === null ? 'create' : 'update',
+        reason,
+        diff: lineDiff(before ?? '', content),
+        target,
+        content,
     };
 }
-async function readPackageJson() {
+function git(gitRoot, args) {
+    return execFileSync('git', args, { cwd: gitRoot, encoding: 'utf8' }).trim();
+}
+/** The ignore rule git applies to `path` (`source` as git names it), or null when none matches. */
+function ignoreRule(gitRoot, path) {
+    let reported;
     try {
-        const raw = await fs.readFile(path.join(process.cwd(), 'package.json'), 'utf-8');
-        return JSON.parse(raw);
-    }
-    catch (err) {
-        // A missing package.json is normal (non-Node projects). Anything else —
-        // unreadable file, malformed JSON — degrades name resolution and
-        // dev-server detection, so say so instead of silently falling back.
-        if (err.code === 'ENOENT') {
+        reported = git(gitRoot, ['check-ignore', '-v', '--no-index', '--', path]);
+    }
+    catch (error) {
+        // Exit status 1: no rule matches.
+        if (error.status === 1)
             return null;
+        throw error;
+    }
+    const rule = /^(.*):\d+:(.*)\t/.exec(reported);
+    if (!rule)
+        throw new Error(`Could not read git's ignore rule for ${path}: ${reported}`);
+    return { source: rule[1], pattern: rule[2] };
+}
+/** Claude Code's Stop hook in the per-developer settings, and the exclude line that keeps that file out of commits. */
+function planStopHook(gitRoot, notices) {
+    if (!isPlainDirectory(join(gitRoot, '.claude')) && !isCLIInstalled('claude'))
+        return [];
+    const settingsPath = `.claude/${CLAUDE_LOCAL_SETTINGS}`;
+    const localPath = claudeSettingsPath(gitRoot, CLAUDE_LOCAL_SETTINGS);
+    if (git(gitRoot, ['ls-files', '--', settingsPath]) !== '') {
+        // A hook that uploads working-tree snapshots is each developer's own opt-in, never inherited from a commit.
+        notices.push(`${settingsPath} is committed to the repository, so init left it alone: a hook there would run for everyone who pulls.`
+            + ` To add Claude Code's Stop hook, untrack it (\`git rm --cached ${settingsPath}\`) and run \`haystack init\` again.`);
+        return [];
+    }
+    // .gitignore outranks .git/info/exclude, so an un-ignore rule there would put the hook in commits whatever init adds.
+    const rule = ignoreRule(gitRoot, settingsPath);
+    if (rule !== null && rule.pattern.startsWith('!') && basename(rule.source) === '.gitignore') {
+        notices.push(`${rule.source} un-ignores ${settingsPath} (${rule.pattern}), so init cannot keep it out of commits and left it alone.`
+            + ' Remove that rule and run `haystack init` again to add Claude Code\'s Stop hook.');
+        return [];
+    }
+    // A settings file init cannot parse costs only the hook: the agent note and onboarding still go ahead.
+    const settings = {};
+    for (const [name, file] of [['local', CLAUDE_LOCAL_SETTINGS], ['shared', CLAUDE_SHARED_SETTINGS]]) {
+        try {
+            settings[name] = readClaudeSettings(claudeSettingsPath(gitRoot, file));
         }
-        const message = err instanceof Error ? err.message : String(err);
-        console.log(chalk.yellow(`⚠ Could not read package.json (${message}); skipping dev-server detection`));
-        return null;
+        catch (error) {
+            notices.push(`.claude/${file} is not valid JSON (${error instanceof Error ? error.message : String(error)}), so init left`
+                + ' Claude Code\'s Stop hook out. Fix the file and run `haystack init` again to add it.');
+            return [];
+        }
+    }
+    const { local, shared } = settings;
+    const changes = [];
+    // Claude Code merges both files: a hook either one carries is installed.
+    const installed = [...claudeEntries(local, 'Stop'), ...claudeEntries(shared, 'Stop')].some(entry => entry.hooks?.some(isPrecomputeCommand));
+    if (!installed && !isInstalledGlobally('haystack')) {
+        notices.push('Claude Code\'s Stop hook runs `haystack`, which is not installed globally here (this run came through npx or a project\'s own copy), so init did not add it.'
+            + ' Install it with `npm install -g @haystackeditor/cli` and run `haystack init` again to add the hook.');
+    }
+    else if (!installed) {
+        const settings = structuredClone(local ?? {});
+        const hooks = (settings.hooks ?? {});
+        settings.hooks = hooks;
+        const entry = { matcher: '', hooks: [{ type: 'command', command: HAYSTACK_PRECOMPUTE_HOOK_COMMAND }] };
+        hooks.Stop = [...claudeEntries(settings, 'Stop'), entry];
+        const content = `${JSON.stringify(settings, null, 2)}\n`;
+        changes.push({
+            path: settingsPath,
+            action: local === undefined ? 'create' : 'update',
+            reason: 'Claude Code prepares each change for `haystack verify` when a session stops (this checkout only).',
+            // An existing file is never echoed: personal settings can hold tokens. Only the entry init adds is shown.
+            diff: local === undefined ? lineDiff('', content)
+                : [' … existing settings, kept as they are', '+ hooks.Stop gains:', ...JSON.stringify(entry, null, 2).split('\n').map(line => `+${line}`)],
+            target: localPath,
+            content,
+        });
+    }
+    if ((changes.length > 0 || existsSync(localPath)) && !isGitIgnored(gitRoot, settingsPath)) {
+        const excludePath = resolve(gitRoot, git(gitRoot, ['rev-parse', '--git-path', 'info/exclude']));
+        const before = existsSync(excludePath) ? readFileSync(excludePath, 'utf8') : '';
+        const line = `/${settingsPath}`;
+        // A line already there is outranked by an un-ignore rule in the same file after it; adding it again would not help.
+        const excluded = before.split('\n').includes(line) ? null : change(gitRoot, excludePath, 'Keeps the per-developer Claude Code settings out of commits.', `${before}${before === '' || before.endsWith('\n') ? '' : '\n'}${line}\n`);
+        if (excluded)
+            changes.push(excluded);
+    }
+    return changes;
+}
+function sameFile(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/** The agent note in AGENTS.md (which Codex, Cursor and most agents read), and in
+ * CLAUDE.md when the repository keeps one that does not import AGENTS.md. */
+function planAgentNotes(gitRoot, notices) {
+    const agents = join(gitRoot, 'AGENTS.md');
+    const claude = join(gitRoot, 'CLAUDE.md');
+    const targets = [];
+    if (isPlainFile(agents) || !(existsSync(agents) || isLink(agents)))
+        targets.push('AGENTS.md');
+    if (isPlainFile(claude) && !/^@AGENTS\.md\b/m.test(readFileSync(claude, 'utf8')))
+        targets.push('CLAUDE.md');
+    if (!targets.includes('AGENTS.md') && !(targets.includes('CLAUDE.md') && sameFile(agents, claude))) {
+        notices.push(`AGENTS.md is not a plain file, so init left it alone. Add this note where your agents read it:\n${AGENT_NOTE}`);
+    }
+    return targets.flatMap(name => {
+        const target = join(gitRoot, name);
+        const before = existsSync(target) ? readFileSync(target, 'utf8') : '';
+        const begin = before.indexOf(NOTE_BEGIN);
+        const end = begin === -1 ? -1 : before.indexOf(NOTE_END, begin);
+        const after = begin !== -1 && end !== -1
+            ? `${before.slice(0, begin)}${AGENT_NOTE}${before.slice(end + NOTE_END.length)}`
+            : before.trim() === '' ? `${AGENT_NOTE}\n`
+                : `${before}${before.endsWith('\n') ? '' : '\n'}\n${AGENT_NOTE}\n`;
+        const planned = change(gitRoot, target, 'Tells coding agents to run `haystack verify` after a change.', after);
+        return planned ? [planned] : [];
+    });
+}
+function isLink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/** Everything init would change in this checkout; reads only. */
+export function planInit(gitRoot) {
+    const notices = [];
+    return { changes: [...planStopHook(gitRoot, notices), ...planAgentNotes(gitRoot, notices)], notices };
+}
+function applyChange(gitRoot, planned) {
+    const inside = relative(gitRoot, planned.target);
+    if (!inside.startsWith('..') && !isAbsolute(inside))
+        assertNoSymlinkOnPath(gitRoot, planned.target);
+    else if (isLink(planned.target))
+        throw new Error(`Refusing to write ${planned.target}: it is a symlink.`);
+    mkdirSync(dirname(planned.target), { recursive: true });
+    writeFileSync(planned.target, planned.content);
+}
+/* -------------------------------------------------------------- command */
+function colored(line) {
+    if (line.startsWith('+'))
+        return chalk.green(line);
+    if (line.startsWith('-'))
+        return chalk.red(line);
+    return chalk.dim(line);
+}
+async function confirmed() {
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return /^y(es)?$/i.test((await prompt.question('Make these changes? [y/N] ')).trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
+export async function initCommand(options) {
+    // In --json mode stdout carries the one document; every other line goes to stderr.
+    const say = (line = '') => { if (options.json)
+        console.error(line);
+    else
+        console.log(line); };
+    const gitRoot = findGitRoot();
+    if (!gitRoot)
+        throw new Error('Run `haystack init` inside a checkout of your app\'s repository.');
+    let origin;
+    try {
+        origin = resolveOriginRepository(gitRoot);
+    }
+    catch {
+        throw new Error('This checkout has no GitHub `origin` remote. Haystack verifies GitHub repositories: add the repository as `origin`, then run `haystack init` again.');
+    }
+    const repository = `${origin.owner}/${origin.repository}`;
+    const plan = planInit(gitRoot);
+    const finish = (status, onboarding, exitCode) => {
+        if (options.json) {
+            const changes = plan.changes.map(({ path, action, reason, diff }) => ({ path, action, reason, diff }));
+            process.stdout.write(`${JSON.stringify(withSchema('init', { status, repository, changes, notices: plan.notices, onboarding }), null, 2)}\n`);
+        }
+        process.exitCode = exitCode;
+    };
+    say(chalk.bold(`Haystack setup for ${repository}`));
+    if (plan.changes.length === 0)
+        say(chalk.dim('Nothing in this checkout needs changing.'));
+    for (const planned of plan.changes) {
+        say('');
+        say(`${chalk.bold(planned.action === 'create' ? 'Create' : 'Update')} ${planned.path}: ${planned.reason}`);
+        for (const line of planned.diff)
+            say(`  ${colored(line)}`);
+    }
+    for (const notice of plan.notices)
+        say(`\n${chalk.yellow(notice)}`);
+    say('');
+    let token;
+    try {
+        token = (await resolveAuthContext({ owner: origin.owner, repo: origin.repository })).token;
+    }
+    catch (error) {
+        if (!(error instanceof NotLoggedInError))
+            throw error;
+        say(chalk.yellow('Not logged in, so nothing was changed. Run `haystack login`, then `haystack init` again.'));
+        finish('login-required', null, EXIT_CODES['login-required']);
+        return;
+    }
+    if (plan.changes.length > 0 && !options.yes) {
+        const interactive = !options.json && process.stdin.isTTY === true && process.stdout.isTTY === true;
+        if (!interactive || !await confirmed()) {
+            say('Nothing was changed. Run `haystack init --yes` to make these changes.');
+            finish('planned', null, EXIT_CODES.planned);
+            return;
+        }
+    }
+    for (const planned of plan.changes) {
+        applyChange(gitRoot, planned);
+        say(chalk.green(`✓ ${planned.action === 'create' ? 'Created' : 'Updated'} ${planned.path}`));
+    }
+    let onboarding;
+    try {
+        onboarding = await startOnboarding(repository, deriveBaseSha(gitRoot, Date.now() + EXPLICIT_WALL_MS), token);
+    }
+    catch (error) {
+        if (error instanceof HaystackApiError && error.code === INSTALLATION_REQUIRED_CODE) {
+            say(chalk.yellow(`Haystack needs its GitHub App on ${origin.owner} to read the repository. Install it at`));
+            say(`  ${HAYSTACK_APP_INSTALL_URL}`);
+            say('then run `haystack init` again.');
+            finish('app-required', null, EXIT_CODES['app-required']);
+            return;
+        }
+        const done = plan.changes.length > 0 ? 'The changes above were made, but onboarding' : 'Onboarding';
+        throw new Error(`${done} could not start: ${error instanceof Error ? error.message : String(error)} Run \`haystack init\` again to start it.`);
+    }
+    reportOnboardingState(onboarding);
+    say(formatOnboarding(onboarding));
+    say('');
+    if (onboarding.state === 'ready')
+        say(chalk.green('Ready. After your next change, run `haystack verify`.'));
+    else if (onboarding.state === 'onboarding') {
+        say(chalk.green('Haystack is preparing the app in the background; the first time can take half an hour.'));
+        say('Keep working: `haystack verify` waits for it when needed, and `haystack verify onboarding --wait` follows it.');
     }
+    finish('done', onboarding, setUpExitCode(onboarding));
 }

package/dist/commands/install-session-hooks.js

@@ -14,13 +14,13 @@
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
-import { join } from 'path';
+import { join, sep } from 'path';
 import { findGitRoot } from '../utils/git.js';
 import { assertNoSymlinkOnPath } from '../utils/safe-write.js';
 // ============================================================================
 // CLI detection (reused from triage runner pattern)
 // ============================================================================
-function isCLIInstalled(name) {
+export function isCLIInstalled(name) {
     try {
         execFileSync(process.platform === 'win32' ? 'where' : 'which', [name], {
             stdio: 'ignore',
@@ -31,6 +31,23 @@ function isCLIInstalled(name) {
         return false;
     }
 }
+/** Whether `name` is installed where a command run later (a Claude Code hook)
+ * finds it. Anything under a node_modules directory is left out: npx, pnpm dlx,
+ * bunx and npm's own project .bin are put on PATH for one run only. */
+export function isInstalledGlobally(name) {
+    const windows = process.platform === 'win32';
+    let found;
+    try {
+        found = execFileSync(windows ? 'where' : 'which', windows ? [name] : ['-a', name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    catch (error) {
+        // Exit status 1: nothing by that name on PATH.
+        if (error.status === 1)
+            return false;
+        throw error;
+    }
+    return found.split(/\r?\n/).some(path => path !== '' && !path.includes(`${sep}node_modules${sep}`));
+}
 function detectInstalledCLIs() {
     const installed = [];
     if (isCLIInstalled('claude'))
@@ -45,27 +62,27 @@ function detectInstalledCLIs() {
 // Claude Code: Native SessionStart hook
 // ============================================================================
 const HAYSTACK_HOOK_COMMAND = 'haystack triage --hook';
-const HAYSTACK_PRECOMPUTE_HOOK_COMMAND = 'haystack verify precompute --hook';
+export const HAYSTACK_PRECOMPUTE_HOOK_COMMAND = 'haystack verify precompute --hook';
 // The per-developer file is the default: a hook that uploads working-tree
 // snapshots must be opted into by each developer, not inherited from a commit.
-const CLAUDE_LOCAL_SETTINGS = 'settings.local.json';
-const CLAUDE_SHARED_SETTINGS = 'settings.json';
-function claudeSettingsPath(gitRoot, fileName) {
+export const CLAUDE_LOCAL_SETTINGS = 'settings.local.json';
+export const CLAUDE_SHARED_SETTINGS = 'settings.json';
+export function claudeSettingsPath(gitRoot, fileName) {
     return join(gitRoot, '.claude', fileName);
 }
-function readClaudeSettings(settingsPath) {
+export function readClaudeSettings(settingsPath) {
     if (!existsSync(settingsPath))
         return undefined;
     return JSON.parse(readFileSync(settingsPath, 'utf-8'));
 }
-function claudeEntries(settings, event) {
+export function claudeEntries(settings, event) {
     const hooks = settings?.hooks;
     const entries = hooks?.[event];
     return Array.isArray(entries) ? entries : [];
 }
 const isTriageCommand = (h) => Boolean(h.command?.includes('haystack triage') || h.command?.includes('haystack check-pending'));
-const isPrecomputeCommand = (h) => Boolean(h.command?.includes(HAYSTACK_PRECOMPUTE_HOOK_COMMAND));
-function isGitIgnored(gitRoot, path) {
+export const isPrecomputeCommand = (h) => Boolean(h.command?.includes(HAYSTACK_PRECOMPUTE_HOOK_COMMAND));
+export function isGitIgnored(gitRoot, path) {
     try {
         execFileSync('git', ['check-ignore', '-q', '--', path], { cwd: gitRoot, stdio: 'ignore' });
         return true;