@spikedpunch/mast 0.3.0 → 0.4.1

package/dist/cli/setup-cmd.js

@@ -0,0 +1,214 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readDoc } from './docs-cmd.js';
+import { buildHookCommand, hookFilePath, localBinCandidates } from './setup-command.js';
+import { HOOK_DEFS, planFor } from './setup-plan.js';
+import { runCursorRules, runStaticSetup, STATIC_HARNESSES } from './setup-static.js';
+import { detectInstallKind } from './upgrade-cmd.js';
+import { PACKAGE_NAME } from './version.js';
+/**
+ * `mast setup <harness>` writes hook configuration and, for harnesses with a rules file
+ * mast can own (or Zed's, via a marked block), that file too. It follows the rules
+ * `skill-install.ts` states: touch nothing it does not own, and be a byte-level no-op on
+ * re-run. Unlike `skill --install` it creates its file when absent, because a hook file
+ * is tool configuration and not a hand-curated prompt (ADR 017 section 3).
+ */
+const HOOK_HARNESSES = ['claude', 'cursor', 'vscode'];
+const ALL_HARNESSES = [...HOOK_HARNESSES, ...STATIC_HARNESSES];
+/** Re-emits `value` in the file's own indentation, line endings and trailing-newline state. */
+function serialize(value, previous) {
+    const indent = previous === null ? '  ' : (/^([ \t]+)\S/m.exec(previous)?.[1] ?? '  ');
+    const trailingNewline = previous === null || previous.endsWith('\n');
+    let text = JSON.stringify(value, null, indent) + (trailingNewline ? '\n' : '');
+    if (previous?.includes('\r\n'))
+        text = text.replace(/\n/g, '\r\n');
+    return text;
+}
+function parseJson(raw) {
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch (error) {
+        return { ok: false, problem: `not valid JSON (${error instanceof Error ? error.message : String(error)})` };
+    }
+}
+function buildCommands(harness, scope, env, localBin) {
+    const commands = {};
+    for (const def of HOOK_DEFS[harness]) {
+        const built = buildHookCommand({
+            harness, event: def.event, installKind: env.installKind, scope, cliEntry: env.cliEntry,
+            ...(localBin !== undefined ? { localBin } : {}),
+        });
+        if (!built.ok)
+            return built;
+        commands[def.event] = built.command;
+    }
+    return { ok: true, commands };
+}
+function notesFor(harness, scope, env) {
+    const notes = [];
+    if (harness === 'vscode') {
+        notes.push('Only the session primer is installed for VS Code. A search reminder is not: VS Code ignores hook matchers, ' +
+            'so it would run on every tool call, and the name of its search tool is not documented.');
+    }
+    if (env.installKind === 'source') {
+        notes.push('The hook command contains a path specific to this machine; do not commit this file.');
+    }
+    if (env.installKind === 'local' && scope === 'project' && harness === 'vscode') {
+        notes.push('The relative command node_modules/.bin/mast is unverified in VS Code: its docs do not say what directory hooks run in.');
+    }
+    return notes;
+}
+function describePlan(plan, existed, remove) {
+    if (remove)
+        return plan.removedCount > 0 ? 'removed' : 'not installed';
+    if (!plan.changed)
+        return 'already up to date';
+    return !existed || plan.items.every((i) => i.state === 'missing') ? 'installed' : 'updated';
+}
+function reportProblem(io, path, problem) {
+    io.err(`mast setup: cannot update ${path}: ${problem}.`);
+    io.err('The file was left unchanged. Fix or delete it, then run the command again.');
+}
+/** Returns the process exit code: 0 done, 1 refused or failed, 2 usage error. */
+export function runSetup(opts, env, io) {
+    const hookHarness = HOOK_HARNESSES.find((h) => h === opts.harness);
+    const staticHarness = STATIC_HARNESSES.find((h) => h === opts.harness);
+    if (hookHarness === undefined && staticHarness === undefined) {
+        io.err(`mast setup: unknown harness "${opts.harness}". Supported: ${ALL_HARNESSES.join(', ')}.`);
+        return 2;
+    }
+    if (opts.check && (opts.remove || opts.dryRun)) {
+        io.err('mast setup: --check cannot be combined with --remove or --dry-run.');
+        return 2;
+    }
+    if (staticHarness !== undefined)
+        return runStaticSetup(staticHarness, opts, env, io);
+    if (hookHarness === undefined)
+        return 2;
+    const hookCode = runHookSetup(hookHarness, opts, env, io);
+    if (hookHarness !== 'cursor')
+        return hookCode;
+    // A failed hooks step stops the rules step, except under --check, which reports both.
+    if (hookCode !== 0 && !opts.check)
+        return hookCode;
+    const rulesCode = runCursorRules(opts, env, io);
+    return hookCode !== 0 ? hookCode : rulesCode;
+}
+function runHookSetup(harness, opts, env, io) {
+    const scope = opts.global ? 'global' : 'project';
+    const path = hookFilePath(harness, scope, opts.projectRoot, env.home);
+    let mode = { kind: 'remove' };
+    if (!opts.remove) {
+        let localBin;
+        if (env.installKind === 'local' && scope === 'project') {
+            const candidates = localBinCandidates(env.cliEntry, opts.projectRoot);
+            localBin = candidates.find((candidate) => io.fileExists(join(opts.projectRoot, candidate)));
+            if (localBin === undefined) {
+                io.err(`mast setup: no mast binary found for the hook command to run. Looked for: ${candidates.map((c) => join(opts.projectRoot, c)).join(', ')}. ` +
+                    `Add mast as a direct dependency of this project or of the package you run it from (pnpm add -D ${PACKAGE_NAME}), or install it globally.`);
+                return 1;
+            }
+        }
+        const built = buildCommands(harness, scope, env, localBin);
+        if (!built.ok) {
+            io.err(`mast setup: ${built.problem}`);
+            return 1;
+        }
+        mode = { kind: 'install', commands: built.commands };
+    }
+    try {
+        const raw = io.readFile(path);
+        let existing = null;
+        if (raw !== null) {
+            const parsed = parseJson(raw);
+            if (!parsed.ok) {
+                reportProblem(io, path, parsed.problem);
+                return 1;
+            }
+            existing = parsed.value;
+        }
+        const plan = planFor(harness, existing, mode);
+        if (!plan.ok) {
+            reportProblem(io, path, plan.problem);
+            return 1;
+        }
+        if (opts.check) {
+            const stale = plan.items.filter((i) => i.state !== 'current');
+            if (stale.length === 0) {
+                io.out(`${path}: already up to date`);
+                return 0;
+            }
+            // A settings file that exists but holds none of mast's hooks is "not installed",
+            // the same as no file: "out of date" would send someone looking for a stale entry.
+            io.out(`${path}: ${stale.length === plan.items.length && stale.every((i) => i.state === 'missing') ? 'not installed' : 'out of date'}`);
+            for (const item of stale)
+                io.out(`  ${item.state === 'missing' ? 'missing' : 'out of date'}: ${item.label}`);
+            return 1;
+        }
+        const status = describePlan(plan, raw !== null, opts.remove);
+        const willWrite = plan.changed;
+        if (opts.dryRun) {
+            io.out(`${path}: ${status} (dry run, nothing written)`);
+            if (willWrite)
+                io.out(plan.next === null ? '(the file would be deleted)' : serialize(plan.next, raw).trimEnd());
+        }
+        else {
+            if (willWrite) {
+                if (plan.next === null)
+                    io.removeFile(path);
+                else
+                    io.writeFileAtomic(path, serialize(plan.next, raw));
+            }
+            io.out(`${path}: ${status}`);
+        }
+        if (!opts.remove)
+            for (const note of notesFor(harness, scope, env))
+                io.out(`Note: ${note}`);
+        return 0;
+    }
+    catch (error) {
+        io.err(`mast setup: ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+export function createNodeSetupIo() {
+    return {
+        readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
+        writeFileAtomic: (path, content) => {
+            // Resolve a symlinked settings file first, or the rename would replace the link
+            // (a dotfiles checkout, say) with a regular file.
+            const target = existsSync(path) ? realpathSync(path) : path;
+            mkdirSync(dirname(target), { recursive: true });
+            // Same directory, so the rename cannot cross a filesystem and stays atomic.
+            const temp = join(dirname(target), `.${basename(target)}.${process.pid}.tmp`);
+            writeFileSync(temp, content);
+            if (existsSync(target))
+                chmodSync(temp, statSync(target).mode & 0o777);
+            renameSync(temp, target);
+        },
+        removeFile: (path) => { rmSync(path); },
+        fileExists: existsSync,
+        directoryExists: (path) => existsSync(path) && statSync(path).isDirectory(),
+        out: (line) => { process.stdout.write(`${line}\n`); },
+        err: (line) => { process.stderr.write(`${line}\n`); },
+    };
+}
+export function registerSetupCommand(program) {
+    program
+        .command('setup <harness> [path]')
+        .description('Install the hooks and rules files that tell an agent to use mast (claude|cursor|vscode|windsurf|zed|desktop)')
+        .option('--global', 'Write the user-level file instead of the project one')
+        .option('--check', 'Write nothing; exit 0 only if everything is installed and current')
+        .option('--remove', 'Remove what mast installed')
+        .option('--dry-run', 'Print the file that would be written, and write nothing')
+        .action((harness, path, opts) => {
+        const projectRoot = resolve(path ?? '.');
+        const moduleDir = dirname(fileURLToPath(import.meta.url));
+        // The home directory is resolved here, at the edge, and nowhere below.
+        process.exitCode = runSetup({ harness, projectRoot, global: opts.global === true, check: opts.check === true, remove: opts.remove === true, dryRun: opts.dryRun === true }, { installKind: detectInstallKind(moduleDir, projectRoot), home: homedir(), cliEntry: join(moduleDir, 'index.js'), skillText: readDoc('skill') }, createNodeSetupIo());
+    });
+}
+//# sourceMappingURL=setup-cmd.js.map

package/dist/cli/setup-cmd.js.map

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

package/dist/cli/setup-command.d.ts

@@ -0,0 +1,47 @@
+import type { Harness, HookEvent } from './hook.js';
+import type { InstallKind } from './upgrade-cmd.js';
+export type SetupScope = 'project' | 'global';
+export interface HookCommandInput {
+    readonly harness: Harness;
+    readonly event: HookEvent;
+    readonly installKind: InstallKind;
+    readonly scope: SetupScope;
+    /** Absolute path of this build's `cli/index.js`; used only for a source checkout. */
+    readonly cliEntry: string;
+    /**
+     * Where a project dependency's binary is, relative to the project root with forward
+     * slashes. Defaults to the root's own `node_modules/.bin/mast`.
+     */
+    readonly localBin?: string;
+}
+export type HookCommandResult = {
+    readonly ok: true;
+    readonly command: string;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+/** The hook file `setup` writes for a harness: project-level, or under the user's home. */
+export declare function hookFilePath(harness: Harness, scope: SetupScope, projectRoot: string, home: string): string;
+/**
+ * Where a project dependency's `mast` binary can be, most likely first, relative to the
+ * project root with forward slashes: beside each `node_modules` this build is running
+ * out of (outermost first), then the project root's own.
+ *
+ * The root is not the only place (D070): a project whose package lives in a
+ * subdirectory has `<sub>/node_modules/.bin/mast` and nothing at the root. The root
+ * stays as the last candidate for a build that runs from outside the project.
+ */
+export declare function localBinCandidates(cliEntry: string, projectRoot: string): string[];
+/**
+ * The command line a harness runs for one hook. Every spelling ends in
+ * ` hook <harness> <event>`: `setup` finds its own entries by that suffix, so the part
+ * before it can change between installs without orphaning the old entry.
+ *
+ * A project-dependency install cannot be written into user-level settings: the path
+ * points into one project's node_modules and fails in every other project.
+ */
+export declare function buildHookCommand(input: HookCommandInput): HookCommandResult;
+/** True when `command` is the one `setup` installs for this harness and event, in any spelling. */
+export declare function isMastCommand(command: string | undefined, harness: Harness, event: HookEvent): boolean;
+//# sourceMappingURL=setup-command.d.ts.map

package/dist/cli/setup-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-command.d.ts","sourceRoot":"","sources":["../../src/cli/setup-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK3G;AAOD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CASlF;AAkBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAa3E;AAED,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAEtG"}

package/dist/cli/setup-command.js

@@ -0,0 +1,76 @@
+import { join, relative, isAbsolute, sep } from 'node:path';
+/** The hook file `setup` writes for a harness: project-level, or under the user's home. */
+export function hookFilePath(harness, scope, projectRoot, home) {
+    const base = scope === 'global' ? home : projectRoot;
+    if (harness === 'claude')
+        return join(base, '.claude', 'settings.json');
+    if (harness === 'cursor')
+        return join(base, '.cursor', 'hooks.json');
+    return scope === 'global' ? join(home, '.copilot', 'hooks', 'mast.json') : join(projectRoot, '.github', 'hooks', 'mast.json');
+}
+// Claude Code expands this variable itself when it runs a project hook, so the spelling
+// holds wherever the project is checked out. A template literal would interpolate it.
+const CLAUDE_PROJECT_DIR = '$' + '{CLAUDE_PROJECT_DIR}';
+const ROOT_LOCAL_BIN = 'node_modules/.bin/mast';
+/**
+ * Where a project dependency's `mast` binary can be, most likely first, relative to the
+ * project root with forward slashes: beside each `node_modules` this build is running
+ * out of (outermost first), then the project root's own.
+ *
+ * The root is not the only place (D070): a project whose package lives in a
+ * subdirectory has `<sub>/node_modules/.bin/mast` and nothing at the root. The root
+ * stays as the last candidate for a build that runs from outside the project.
+ */
+export function localBinCandidates(cliEntry, projectRoot) {
+    const rel = relative(projectRoot, cliEntry);
+    const segments = rel.startsWith('..') || isAbsolute(rel) ? [] : rel.split(sep);
+    const candidates = [];
+    segments.forEach((segment, index) => {
+        if (segment === 'node_modules')
+            candidates.push([...segments.slice(0, index + 1), '.bin', 'mast'].join('/'));
+    });
+    if (!candidates.includes(ROOT_LOCAL_BIN))
+        candidates.push(ROOT_LOCAL_BIN);
+    return candidates;
+}
+// A path made only of these needs no quoting in a POSIX shell. The plain spelling is
+// kept for them so a file written by 0.4.0 still compares as current.
+const SHELL_SAFE = /^[A-Za-z0-9_@+.\/-]+$/;
+function escapeForDoubleQuotes(text) {
+    return text.replace(/["\\$`]/g, (ch) => `\\${ch}`);
+}
+function localCommand(harness, localBin) {
+    if (SHELL_SAFE.test(localBin)) {
+        return harness === 'claude' ? `"${CLAUDE_PROJECT_DIR}"/${localBin}` : localBin;
+    }
+    const quoted = escapeForDoubleQuotes(localBin);
+    return harness === 'claude' ? `"${CLAUDE_PROJECT_DIR}/${quoted}"` : `"${quoted}"`;
+}
+/**
+ * The command line a harness runs for one hook. Every spelling ends in
+ * ` hook <harness> <event>`: `setup` finds its own entries by that suffix, so the part
+ * before it can change between installs without orphaning the old entry.
+ *
+ * A project-dependency install cannot be written into user-level settings: the path
+ * points into one project's node_modules and fails in every other project.
+ */
+export function buildHookCommand(input) {
+    const tail = ` hook ${input.harness} ${input.event}`;
+    if (input.installKind === 'global')
+        return { ok: true, command: `mast${tail}` };
+    if (input.installKind === 'source')
+        return { ok: true, command: `node "${input.cliEntry}"${tail}` };
+    if (input.scope === 'global') {
+        return {
+            ok: false,
+            problem: 'this mast is a project dependency, and a user-level hook that points into one project\'s node_modules ' +
+                'breaks in every other project. Install mast globally, or run without --global.',
+        };
+    }
+    return { ok: true, command: `${localCommand(input.harness, input.localBin ?? ROOT_LOCAL_BIN)}${tail}` };
+}
+/** True when `command` is the one `setup` installs for this harness and event, in any spelling. */
+export function isMastCommand(command, harness, event) {
+    return command !== undefined && command.endsWith(` hook ${harness} ${event}`);
+}
+//# sourceMappingURL=setup-command.js.map

package/dist/cli/setup-command.js.map

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

package/dist/cli/setup-plan.d.ts

@@ -0,0 +1,52 @@
+import type { Harness, HookEvent } from './hook.js';
+interface HookDef {
+    readonly event: HookEvent;
+    /** The harness's own name for the event, which is also the key in its hooks object. */
+    readonly nativeEvent: string;
+    readonly matcher?: string;
+    readonly timeout: number;
+}
+/**
+ * The hooks each harness gets. The Claude session-start group has no matcher on purpose:
+ * that matches every source, including `compact`. VS Code has no search hook because its
+ * docs say matchers are ignored (it would run on every tool call) and the search tool's
+ * name is undocumented.
+ */
+export declare const HOOK_DEFS: Readonly<Record<Harness, readonly HookDef[]>>;
+export type Commands = Readonly<Partial<Record<HookEvent, string>>>;
+export type PlanMode = {
+    readonly kind: 'install';
+    readonly commands: Commands;
+} | {
+    readonly kind: 'remove';
+};
+export type ItemState = 'missing' | 'outdated' | 'current';
+export interface PlanItem {
+    readonly label: string;
+    readonly state: ItemState;
+}
+export type PlanResult = {
+    readonly ok: true;
+    /** The whole file's next value, or null when the file should be deleted. */
+    readonly next: object | null;
+    /** False means the file must not be written at all. */
+    readonly changed: boolean;
+    /** Install mode: the state of each hook found. */
+    readonly items: readonly PlanItem[];
+    /** Remove mode: how many of mast's entries were taken out. */
+    readonly removedCount: number;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+/**
+ * Claude Code: `hooks.<Event>` is a list of groups, each `{matcher?, hooks: [handler]}`.
+ * Within a group only mast's handler is touched; a group mast empties is removed, a group
+ * with other handlers keeps them.
+ */
+export declare function planClaude(existing: unknown, mode: PlanMode): PlanResult;
+export declare const planCursor: (existing: unknown, mode: PlanMode) => PlanResult;
+export declare const planVscode: (existing: unknown, mode: PlanMode) => PlanResult;
+export declare function planFor(harness: Harness, existing: unknown, mode: PlanMode): PlanResult;
+export {};
+//# sourceMappingURL=setup-plan.d.ts.map

package/dist/cli/setup-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-plan.d.ts","sourceRoot":"","sources":["../../src/cli/setup-plan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAOpD,UAAU,OAAO;IACf,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC,CAUnE,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AACpE,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAC3D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAED,MAAM,MAAM,UAAU,GAClB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AA2CrD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,UAAU,CA6ExE;AA2ED,eAAO,MAAM,UAAU,GAAI,UAAU,OAAO,EAAE,MAAM,QAAQ,KAAG,UAAgD,CAAC;AAChH,eAAO,MAAM,UAAU,GAAI,UAAU,OAAO,EAAE,MAAM,QAAQ,KAAG,UAAgD,CAAC;AAEhH,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,UAAU,CAGvF"}

package/dist/cli/setup-plan.js

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+import { isMastCommand } from './setup-command.js';
+/** Seconds, in all three harnesses. Session start builds the primer; search must stay cheap. */
+const SESSION_START_TIMEOUT = 30;
+const SEARCH_TIMEOUT = 5;
+/**
+ * The hooks each harness gets. The Claude session-start group has no matcher on purpose:
+ * that matches every source, including `compact`. VS Code has no search hook because its
+ * docs say matchers are ignored (it would run on every tool call) and the search tool's
+ * name is undocumented.
+ */
+export const HOOK_DEFS = {
+    claude: [
+        { event: 'session-start', nativeEvent: 'SessionStart', timeout: SESSION_START_TIMEOUT },
+        { event: 'search', nativeEvent: 'PreToolUse', matcher: 'Grep|Glob', timeout: SEARCH_TIMEOUT },
+    ],
+    cursor: [
+        { event: 'session-start', nativeEvent: 'sessionStart', timeout: SESSION_START_TIMEOUT },
+        { event: 'search', nativeEvent: 'postToolUse', matcher: 'Grep', timeout: SEARCH_TIMEOUT },
+    ],
+    vscode: [{ event: 'session-start', nativeEvent: 'SessionStart', timeout: SESSION_START_TIMEOUT }],
+};
+// Zod is used to validate, not to rebuild: a parsed loose object puts its known keys
+// first, which would reorder a user's file. `passThrough` validates and hands back the
+// original value, so key order survives and only mast's entries are edited.
+const rootShape = z.looseObject({ hooks: z.looseObject({}).optional() });
+const handlerShape = z.looseObject({ command: z.string().optional() });
+const groupShape = z.looseObject({ matcher: z.string().optional(), hooks: z.array(handlerShape) });
+const flatEntryShape = z.looseObject({ command: z.string().optional() });
+function passThrough(schema) {
+    return z.custom((value) => schema.safeParse(value).success);
+}
+function readTyped(schema, value, where) {
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        const found = result.error.issues
+            .slice(0, 3)
+            .map((issue) => `${[where, ...issue.path.map(String)].join('.')}: ${issue.message}`);
+        return { ok: false, problem: `unexpected structure (${found.join('; ')})` };
+    }
+    return { ok: true, data: structuredClone(passThrough(schema).parse(value)) };
+}
+function readRoot(existing) {
+    return existing === null ? { ok: true, data: {} } : readTyped(rootShape, existing, 'file');
+}
+const fail = (problem) => ({ ok: false, problem });
+function hooksOf(root) {
+    const hooks = root.hooks ?? {};
+    root.hooks = hooks;
+    return hooks;
+}
+/**
+ * Claude Code: `hooks.<Event>` is a list of groups, each `{matcher?, hooks: [handler]}`.
+ * Within a group only mast's handler is touched; a group mast empties is removed, a group
+ * with other handlers keeps them.
+ */
+export function planClaude(existing, mode) {
+    const rootRead = readRoot(existing);
+    if (!rootRead.ok)
+        return fail(rootRead.problem);
+    const root = rootRead.data;
+    const items = [];
+    let removedCount = 0;
+    let changed = false;
+    for (const def of HOOK_DEFS.claude) {
+        const rawGroups = root.hooks?.[def.nativeEvent];
+        const read = rawGroups === undefined ? null : readTyped(z.array(groupShape), rawGroups, `hooks.${def.nativeEvent}`);
+        if (read !== null && !read.ok)
+            return fail(read.problem);
+        let groups = read === null ? [] : read.data;
+        const isMast = (command) => isMastCommand(command, 'claude', def.event);
+        const touched = new Set();
+        if (mode.kind === 'remove') {
+            for (const group of groups) {
+                const kept = group.hooks.filter((h) => !isMast(h.command));
+                if (kept.length === group.hooks.length)
+                    continue;
+                removedCount += group.hooks.length - kept.length;
+                group.hooks = kept;
+                touched.add(group);
+            }
+            if (touched.size === 0)
+                continue;
+            groups = groups.filter((g) => !touched.has(g) || g.hooks.length > 0);
+            changed = true;
+            if (groups.length === 0)
+                delete hooksOf(root)[def.nativeEvent];
+            else
+                hooksOf(root)[def.nativeEvent] = groups;
+            continue;
+        }
+        const command = mode.commands[def.event];
+        if (command === undefined)
+            continue;
+        const handler = { type: 'command', command, timeout: def.timeout };
+        const found = groups.flatMap((group) => group.hooks.filter((h) => isMast(h.command)).map((h) => ({ group, h })));
+        const first = found[0];
+        const duplicates = found.slice(1);
+        const fresh = () => ({ ...(def.matcher === undefined ? {} : { matcher: def.matcher }), hooks: [{ ...handler }] });
+        let state = 'current';
+        if (first === undefined) {
+            groups.push(fresh());
+            state = 'missing';
+        }
+        else {
+            const sameHandler = first.h['type'] === handler.type && first.h.command === command && first.h['timeout'] === handler.timeout;
+            if (!sameHandler || first.group.matcher !== def.matcher) {
+                state = 'outdated';
+                const ownsGroup = first.group.hooks.every((h) => isMast(h.command));
+                if (ownsGroup || first.group.matcher === def.matcher) {
+                    Object.assign(first.h, handler);
+                    if (ownsGroup) {
+                        if (def.matcher === undefined)
+                            delete first.group.matcher;
+                        else
+                            first.group.matcher = def.matcher;
+                    }
+                }
+                else {
+                    // The group's matcher also scopes someone else's handler, so it cannot be edited.
+                    first.group.hooks = first.group.hooks.filter((h) => h !== first.h);
+                    touched.add(first.group);
+                    groups.push(fresh());
+                }
+            }
+        }
+        for (const dup of duplicates) {
+            dup.group.hooks = dup.group.hooks.filter((h) => h !== dup.h);
+            touched.add(dup.group);
+            state = 'outdated';
+        }
+        groups = groups.filter((g) => !touched.has(g) || g.hooks.length > 0);
+        items.push({ label: def.nativeEvent, state });
+        if (state !== 'current') {
+            changed = true;
+            hooksOf(root)[def.nativeEvent] = groups;
+        }
+    }
+    return { ok: true, next: root, changed, items, removedCount };
+}
+/** Cursor (`hooks.json`) and VS Code (`mast.json`): `hooks.<event>` is a flat list of entries. */
+function planFlat(harness, existing, mode) {
+    const rootRead = readRoot(existing);
+    if (!rootRead.ok)
+        return fail(rootRead.problem);
+    const root = rootRead.data;
+    const items = [];
+    let removedCount = 0;
+    let changed = false;
+    if (mode.kind === 'install' && harness === 'cursor' && !('version' in root)) {
+        root['version'] = 1;
+        items.push({ label: 'version', state: 'missing' });
+        changed = true;
+    }
+    for (const def of HOOK_DEFS[harness]) {
+        const rawEntries = root.hooks?.[def.nativeEvent];
+        const read = rawEntries === undefined ? null : readTyped(z.array(flatEntryShape), rawEntries, `hooks.${def.nativeEvent}`);
+        if (read !== null && !read.ok)
+            return fail(read.problem);
+        const entries = read === null ? [] : read.data;
+        const isMast = (e) => isMastCommand(e.command, harness, def.event);
+        if (mode.kind === 'remove') {
+            const kept = entries.filter((e) => !isMast(e));
+            if (kept.length === entries.length)
+                continue;
+            removedCount += entries.length - kept.length;
+            changed = true;
+            if (kept.length === 0)
+                delete hooksOf(root)[def.nativeEvent];
+            else
+                hooksOf(root)[def.nativeEvent] = kept;
+            continue;
+        }
+        const command = mode.commands[def.event];
+        if (command === undefined)
+            continue;
+        const wanted = harness === 'cursor'
+            ? { command, type: 'command', ...(def.matcher === undefined ? {} : { matcher: def.matcher }), timeout: def.timeout }
+            : { type: 'command', command, timeout: def.timeout };
+        const found = entries.filter(isMast);
+        const first = found[0];
+        let state = 'current';
+        let next = entries;
+        if (first === undefined) {
+            next = [...entries, wanted];
+            state = 'missing';
+        }
+        else {
+            const same = Object.entries(wanted).every(([key, value]) => first[key] === value) && 'matcher' in first === 'matcher' in wanted;
+            if (!same) {
+                Object.assign(first, wanted);
+                if (!('matcher' in wanted))
+                    delete first['matcher'];
+                state = 'outdated';
+            }
+            if (found.length > 1) {
+                next = entries.filter((e) => e === first || !isMast(e));
+                state = 'outdated';
+            }
+        }
+        items.push({ label: def.nativeEvent, state });
+        if (state !== 'current') {
+            changed = true;
+            hooksOf(root)[def.nativeEvent] = next;
+        }
+    }
+    // mast.json belongs to mast outright: once its last entry goes, so does the file.
+    const hooksLeft = root.hooks === undefined ? 0 : Object.keys(root.hooks).length;
+    if (harness === 'vscode' && removedCount > 0 && Object.keys(root).length === 1 && hooksLeft === 0) {
+        return { ok: true, next: null, changed, items, removedCount };
+    }
+    return { ok: true, next: root, changed, items, removedCount };
+}
+export const planCursor = (existing, mode) => planFlat('cursor', existing, mode);
+export const planVscode = (existing, mode) => planFlat('vscode', existing, mode);
+export function planFor(harness, existing, mode) {
+    if (harness === 'claude')
+        return planClaude(existing, mode);
+    return harness === 'cursor' ? planCursor(existing, mode) : planVscode(existing, mode);
+}
+//# sourceMappingURL=setup-plan.js.map