syntaur 0.14.0 → 0.16.0

package/dist/launch/index.d.ts

@@ -0,0 +1,318 @@
+import { SpawnOptions, ChildProcess } from 'node:child_process';
+
+type OpenUrlErrorCode = 'bad-scheme' | 'bad-host' | 'missing-id' | 'both-ids' | 'malformed' | 'duplicate-param' | 'bad-mode';
+declare class OpenUrlError extends Error {
+    readonly code: OpenUrlErrorCode;
+    constructor(code: OpenUrlErrorCode, message: string);
+}
+type SessionMode = 'resume' | 'fork';
+interface ParsedOpenUrl {
+    kind: 'assignment' | 'session';
+    id: string;
+    /**
+     * Only set when `kind === 'session'`. Defaults to `'resume'` when the URL
+     * has no `mode` query param. Distinguishes "continue this session under the
+     * same id" (resume) from "branch a new session id at this point in
+     * history" (fork) so the dashboard can disable Resume while the original
+     * process may still be writing the transcript.
+     */
+    mode?: SessionMode;
+}
+/**
+ * Parse a `syntaur://open?assignment=<id>` or `syntaur://open?session=<id>` URL.
+ *
+ * Validation:
+ * - scheme must be `syntaur:`
+ * - host must be `open`
+ * - exactly one of `assignment` or `session` query params must be present
+ * - neither param may be duplicated
+ * - when `session` is present, optional `mode=resume|fork` (default `resume`)
+ *
+ * Throws OpenUrlError with a structured code on any failure.
+ */
+declare function parseOpenUrl(input: string): ParsedOpenUrl;
+
+type BindableActionKind = 'new-workspace' | 'new-project' | 'new-todo' | 'new-assignment';
+
+type PromptArgPosition = 'first' | 'last' | 'none';
+/**
+ * Per-agent argv recipe for continuing a recorded session in a specific mode.
+ *
+ * `args` is a literal argv list with the substring `{id}` substituted for the
+ * agent's session id at launch time. `command` overrides the agent's main
+ * `command` field — used by subcommand-style agents (e.g. `codex resume <id>`
+ * is documented as command=codex, args=['resume','{id}']; the override exists
+ * for future agents whose subcommand binary differs).
+ */
+interface SessionInvocation {
+    command?: string;
+    args: string[];
+}
+interface AgentConfig {
+    id: string;
+    label: string;
+    command: string;
+    args?: string[];
+    promptArgPosition?: PromptArgPosition;
+    default?: boolean;
+    resolveFromShellAliases?: boolean;
+    resume?: SessionInvocation;
+    fork?: SessionInvocation;
+}
+
+interface StatusDefinition {
+    id: string;
+    label: string;
+    description?: string;
+    color?: string;
+    icon?: string;
+    terminal?: boolean;
+}
+interface StatusTransition {
+    from: string;
+    command: string;
+    to: string;
+    label?: string;
+    description?: string;
+    requiresReason?: boolean;
+}
+interface StatusConfig {
+    statuses: StatusDefinition[];
+    order: string[];
+    transitions: StatusTransition[];
+}
+interface TypeDefinition {
+    id: string;
+    label?: string;
+    description?: string;
+    color?: string;
+    icon?: string;
+}
+interface TypesConfig {
+    definitions: TypeDefinition[];
+    default: string;
+}
+interface IntegrationConfig {
+    claudePluginDir: string | null;
+    codexPluginDir: string | null;
+    codexMarketplacePath: string | null;
+}
+interface OnboardingConfig {
+    completed: boolean;
+}
+interface BackupConfig {
+    repo: string | null;
+    categories: string;
+    lastBackup: string | null;
+    lastRestore: string | null;
+}
+type AutoCreateWorktree = 'skip' | 'ask' | 'always';
+interface PlaybooksConfig {
+    disabled: string[];
+}
+interface ThemeConfig {
+    preset: string;
+}
+interface HotkeyBindingsConfig {
+    bindings: Partial<Record<BindableActionKind, string>>;
+}
+type TerminalChoice = 'terminal-app' | 'iterm' | 'ghostty' | 'alacritty' | 'warp' | 'kitty';
+interface SyntaurConfig {
+    version: string;
+    defaultProjectDir: string;
+    onboarding: OnboardingConfig;
+    agentDefaults: {
+        trustLevel: 'low' | 'medium' | 'high';
+        autoApprove: boolean;
+        autoCreateWorktree: AutoCreateWorktree;
+    };
+    integrations: IntegrationConfig;
+    backup: BackupConfig | null;
+    statuses: StatusConfig | null;
+    types: TypesConfig | null;
+    agents: AgentConfig[] | null;
+    playbooks: PlaybooksConfig;
+    theme: ThemeConfig | null;
+    hotkeys: HotkeyBindingsConfig | null;
+    terminal: TerminalChoice | null;
+}
+
+/**
+ * The resolved command + args shape returned by both fresh-launch and
+ * resume-launch argv builders. When `resolveFromShellAliases: true` is set on
+ * the agent, `command` is rewritten to the user's shell (or /bin/sh fallback)
+ * and `args` becomes `['-i', '-c', '<quoted invocation>']` — so callers must
+ * consume both fields, not just args.
+ */
+interface ResolvedArgv {
+    command: string;
+    args: string[];
+}
+interface BuiltArgv {
+    argv: ResolvedArgv;
+    shellFallbackWarning: string | null;
+}
+
+type LaunchErrorCode = 'no-agents-configured' | 'assignment-not-found' | 'session-not-found' | 'agent-not-configured' | 'mode-not-supported';
+declare class LaunchError extends Error {
+    readonly code: LaunchErrorCode;
+    constructor(code: LaunchErrorCode, message: string);
+}
+interface LaunchPlan {
+    terminal: TerminalChoice;
+    cwd: string;
+    argv: ResolvedArgv;
+    env: NodeJS.ProcessEnv;
+    agentId: string;
+    /** Non-fatal warning about a fallback cwd (worktree path missing). */
+    fallbackWarning: string | null;
+    /** Non-fatal warning from shell-alias resolution falling back to /bin/sh. */
+    shellFallbackWarning: string | null;
+}
+interface ResolveLaunchPlanInput {
+    kind: 'assignment' | 'session';
+    id: string;
+    /**
+     * Only consulted when `kind === 'session'`. Defaults to `'resume'` so
+     * callers that haven't been updated to thread the URL mode through still
+     * get the prior behavior (continue the same session id).
+     */
+    mode?: SessionMode;
+    config: SyntaurConfig;
+    projectsDir: string;
+    assignmentsDir: string;
+}
+/**
+ * Pick the agent the "Open in agent" flow should use. Order of preference:
+ * - the first agent with `default: true`
+ * - else the first entry in the list
+ * Throws LaunchError('no-agents-configured') if the list is empty (only
+ * possible when the user explicitly wrote `agents: []` — absence falls back to
+ * BUILTIN_AGENTS via `getAgents()`).
+ */
+declare function pickAgent(config: SyntaurConfig): AgentConfig;
+/**
+ * Resolve the launch plan for a "Open in agent" click. Reads the assignment or
+ * session record, picks the cwd + agent, builds the argv, and returns a
+ * structured plan that `executeLaunchPlan` (or an Electron caller) can run.
+ */
+declare function resolveLaunchPlan(input: ResolveLaunchPlanInput): Promise<LaunchPlan>;
+
+declare class TerminalNotFoundError extends Error {
+    readonly terminal: TerminalChoice;
+    readonly remediation: string;
+    constructor(terminal: TerminalChoice, remediation: string);
+}
+/**
+ * Test hook: a function that replaces `child_process.spawn` so unit tests can
+ * assert exactly what the launcher invoked without spawning real processes.
+ * Must return a `ChildProcess`-shaped object — `executeLaunchPlan` listens for
+ * `'error'`, `'spawn'`, and `'exit'` events to detect missing terminals.
+ */
+type SpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+/**
+ * Run the launch plan: spawn the configured terminal in a new window with the
+ * resolved cwd + agent argv. Returns once the spawn has been initiated and
+ * confirmed; for wrapper commands (osascript/open) it briefly waits for the
+ * wrapper to exit so that missing apps surface as a non-zero CLI exit.
+ *
+ * Throws `TerminalNotFoundError` when the spawn errors (ENOENT on direct CLI
+ * launchers) or when a wrapper exits non-zero (target app missing).
+ */
+declare function executeLaunchPlan(plan: LaunchPlan, spawnFn?: SpawnFn): Promise<void>;
+interface TerminalInvocation {
+    command: string;
+    args: string[];
+}
+/**
+ * Build the argv that will be handed to `spawn` to open `plan.argv` in a new
+ * window of `plan.terminal` at `plan.cwd`. Exported for unit testing.
+ */
+declare function buildTerminalInvocation(plan: LaunchPlan): TerminalInvocation;
+
+/**
+ * Build argv for an agent launch. Handles:
+ * - `resolveFromShellAliases: true` → `$SHELL -i -c '<quoted...>'`
+ * - `promptArgPosition: 'first' | 'last' | 'none'`
+ * - plain absolute or bare-name command.
+ */
+declare function buildAgentArgv(agent: AgentConfig, prompt: string, env?: NodeJS.ProcessEnv): BuiltArgv;
+
+/**
+ * Re-export the fresh-launch argv builder under a parallel name so the launch
+ * core has a single import surface: `buildFreshArgv` (new run) and
+ * `buildSessionArgv` (resume/fork an existing session).
+ */
+declare const buildFreshArgv: typeof buildAgentArgv;
+/**
+ * Build argv for continuing an existing agent session under a specific mode.
+ *
+ * The argv shape per agent is declared in `AgentConfig.resume` / `.fork`
+ * (`SessionInvocation`):
+ *   - `args` is a literal argv list. The substring `{id}` is replaced with
+ *     `sessionId`.
+ *   - `command` optionally overrides `agent.command` for subcommand-style
+ *     agents whose binary differs (none in builtins).
+ *
+ * Existing `agent.args` (the base flags applied to a fresh launch — e.g.
+ * `--dangerously-skip-permissions`) are preserved and prefixed before the
+ * invocation args, matching the prior `buildResumeArgv` behavior.
+ *
+ * The `resolveFromShellAliases` rewriting is preserved identically: the
+ * command is rewritten to `$SHELL`/`/bin/sh` and args become
+ * `['-i', '-c', '<quoted>']`. The quoted command line uses the (possibly
+ * overridden) executable.
+ *
+ * Throws `LaunchError('mode-not-supported', ...)` when the agent has no
+ * entry for the requested mode.
+ */
+declare function buildSessionArgv(agent: AgentConfig, sessionId: string, mode: SessionMode, env?: NodeJS.ProcessEnv): BuiltArgv;
+
+type InstallKind = 'npx' | 'global' | 'local' | 'unknown';
+interface DetectOptions {
+    realpath?: (p: string) => string;
+    readFile?: (p: string) => string;
+    envUserAgent?: string;
+}
+/**
+ * Classify the install origin of the running CLI.
+ *
+ * Decision order:
+ *   1. npx-style cache patterns (anchored to `/node_modules/` suffix).
+ *   2. `npm_config_user_agent` containing `npx/` (some pnpm-shim invocations
+ *      don't put dlx in the path).
+ *   3. Canonical npm global layout `/lib/node_modules/syntaur/`.
+ *   4. Local checkout (walks up to find a `package.json` named `syntaur`
+ *      whose dir is not under any `node_modules/`).
+ *   5. `unknown` — the subcommand refuses these alongside `npx` to avoid
+ *      registering a bundle path that may not survive.
+ */
+declare function detectInstallKind(scriptUrl: string, opts?: DetectOptions): InstallKind;
+/**
+ * Extract the cache-hash segment from an npx-style script URL.
+ * Returns null for global/local/unknown installs.
+ */
+declare function extractNpxHash(scriptUrl: string, opts?: DetectOptions): string | null;
+declare function nudgeStampDir(): string;
+declare function nudgeStampPath(hash: string): string;
+declare function hasNudgedHash(hash: string): Promise<boolean>;
+declare function recordNudge(hash: string): Promise<void>;
+/**
+ * Truthiness rules for `SYNTAUR_SKIP_HANDLER_NUDGE`:
+ *   - `'1'`, `'true'`, `'yes'` (case-insensitive, trimmed) → disabled
+ *   - empty, unset, `'0'`, `'false'`, whitespace → enabled
+ *
+ * Deliberately narrow so users who set the var to `'0'` to mean "off the
+ * skip" don't accidentally disable the nudge.
+ */
+declare function isHandlerNudgeDisabled(): boolean;
+declare function nudgeMessage(): string;
+declare function shouldNudgeForNpx(hash: string | null): Promise<boolean>;
+/**
+ * Pre-Commander startup hook. Mirrors `maybePromptInstall` from
+ * `src/utils/npx-prompt.ts` in shape so `src/index.ts` can call them
+ * back-to-back.
+ */
+declare function maybeNudgeForNpxInstall(scriptUrl: string): Promise<void>;
+
+export { type BuiltArgv, type InstallKind, LaunchError, type LaunchErrorCode, type LaunchPlan, OpenUrlError, type OpenUrlErrorCode, type ParsedOpenUrl, type ResolveLaunchPlanInput, type ResolvedArgv, type SessionMode, type SpawnFn, TerminalNotFoundError, buildFreshArgv, buildSessionArgv, buildTerminalInvocation, detectInstallKind, executeLaunchPlan, extractNpxHash, hasNudgedHash, isHandlerNudgeDisabled, maybeNudgeForNpxInstall, nudgeMessage, nudgeStampDir, nudgeStampPath, parseOpenUrl, pickAgent, recordNudge, resolveLaunchPlan, shouldNudgeForNpx };