@dalmasonto/taskflow-mcp 2.5.1 → 2.7.0

package/dist/init.d.ts

@@ -0,0 +1,150 @@
+/**
+ * `taskflow init` (also `taskflow-mcp init`) — the post-install walkthrough.
+ *
+ * Asks which coding agent(s) ("harnesses") to wire up and at what scope, then:
+ *   1. registers the `taskflow-mcp` server with each harness — through the
+ *      harness's own CLI when it is on PATH, else by merging its config file;
+ *   2. for Claude Code, offers the lifecycle hooks;
+ *   3. finds `.taskflow.json`, or creates one by minting an agent when given a
+ *      user token (reusing `--mint`'s request), or explains the manual step;
+ *   4. runs the `--doctor` check;
+ *   5. prints the next steps, ending at the web app.
+ *
+ * Everything that touches the outside world — files, PATH, child processes,
+ * the network, the terminal — comes in through {@link InitDeps}, so the plan
+ * and the merges are tested against fake paths and never the real home dir.
+ */
+import { type TaskflowConfig } from "./config.js";
+import { type FetchLike } from "./mint.js";
+/** The hosted app. A self-hosted install passes `--app-url`. */
+export declare const DEFAULT_APP_URL = "https://taskflow.supercodehive.com";
+/** The hosted API — what `.taskflow.json`'s `server` points at. */
+export declare const DEFAULT_SERVER_URL = "https://api.taskflow.supercodehive.com";
+export declare const HARNESSES: readonly ["claude", "codex", "gemini", "cursor", "opencode"];
+export type Harness = (typeof HARNESSES)[number];
+export type Scope = "user" | "project";
+export declare const HARNESS_LABEL: Record<Harness, string>;
+/** A clear, user-facing failure. */
+export declare class InitError extends Error {
+    constructor(message: string);
+}
+export interface InitArgs {
+    harnesses: Harness[];
+    scope: Scope | undefined;
+    yes: boolean;
+    dryRun: boolean;
+    /** undefined = ask (interactive) / yes (with --yes). */
+    hooks: boolean | undefined;
+    dir: string | undefined;
+    server: string | undefined;
+    project: number | undefined;
+    token: string | undefined;
+    profile: string;
+    displayName: string | undefined;
+    appUrl: string | undefined;
+    doctor: boolean;
+    help: boolean;
+}
+export declare const INIT_USAGE = "taskflow init \u2014 connect your coding agent to TaskFlow\n\n  taskflow init                      Interactive walkthrough.\n  taskflow init --harness claude --scope user --yes\n                                     Non-interactive (scripts / CI).\n\nOptions:\n  --harness <names>   claude, codex, gemini, cursor, opencode (comma-separated,\n                      repeatable, or \"all\").\n  --scope <s>         user (global, every project) or project (this repo only).\n  --dir <path>        Project root for --scope project and .taskflow.json\n                      (default: the current directory).\n  --hooks / --no-hooks\n                      Install the Claude Code lifecycle hooks (default: yes).\n  --server <url>      TaskFlow API for a new .taskflow.json\n                      (default: https://api.taskflow.supercodehive.com).\n  --project <id>      Project id to link an agent in.\n  --token <t>         YOUR user token (or TASKFLOW_USER_TOKEN) \u2014 with --project,\n                      mints an agent and writes .taskflow.json.\n  --profile <name>    Profile name for the minted agent (default: main).\n  --display-name <s>  Display name for the minted agent.\n  --app-url <url>     Your TaskFlow web app, when self-hosting\n                      (default: https://taskflow.supercodehive.com).\n  --no-doctor         Skip the connection check at the end.\n  --dry-run           Print what would run / be written; change nothing.\n  -y, --yes           Accept defaults; never prompt.\n  -h, --help          This message.";
+export declare function parseHarnesses(value: string): Harness[];
+export declare function parseScope(value: string): Scope;
+/** Parse `init`'s arguments (without the `init` word itself). */
+export declare function parseInitArgs(argv: string[], env?: NodeJS.ProcessEnv): InitArgs;
+/** Read-only view of the machine, for planning. */
+export interface PlanEnv {
+    home: string;
+    /** The project root (for project scope and `.taskflow.json`). */
+    dir: string;
+    env: NodeJS.ProcessEnv;
+    readFile(path: string): string | null;
+    exists(path: string): boolean;
+    /** Whether an executable is on PATH. */
+    which(cmd: string): boolean;
+}
+export type Action = {
+    kind: "exec";
+    harness: Harness;
+    summary: string;
+    cmd: string;
+    args: string[];
+    /** Tried when the command fails for a reason other than "already exists". */
+    fallback?: Action;
+} | {
+    kind: "write";
+    harness: Harness | "taskflow";
+    summary: string;
+    path: string;
+    before: string | null;
+    after: string;
+} | {
+    kind: "skip";
+    harness: Harness | "taskflow";
+    summary: string;
+} | {
+    kind: "manual";
+    harness: Harness | "taskflow";
+    summary: string;
+    lines: string[];
+};
+/** Where each harness keeps its MCP config, per scope. `null` = no such scope. */
+export declare function harnessConfigPath(h: Harness, scope: Scope, p: PlanEnv): string | null;
+/** Manual instructions for one harness — the fallback when we won't write. */
+export declare function manualInstructions(h: Harness, scope: Scope, p: PlanEnv): string[];
+/** Plan the MCP registration for one harness. */
+export declare function planRegistration(h: Harness, requested: Scope, p: PlanEnv): Action[];
+/** Plan the Claude Code hooks. */
+export declare function planHooks(scope: Scope, p: PlanEnv): Action;
+export interface PlanInput {
+    harnesses: Harness[];
+    scope: Scope;
+    hooks: boolean;
+}
+/** The whole registration plan. Pure over {@link PlanEnv}. */
+export declare function buildPlan(input: PlanInput, p: PlanEnv): Action[];
+/** Render a plan for `--dry-run` (and for the confirm prompt). */
+export declare function describePlan(actions: Action[], withDiffs: boolean): string[];
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Side-effecting operations. */
+export interface ApplyDeps {
+    writeFile(path: string, text: string, mode?: number): void;
+    copyFile(from: string, to: string): void;
+    mkdirp(dir: string): void;
+    exists(path: string): boolean;
+    exec(cmd: string, args: string[]): ExecResult;
+    log(line: string): void;
+}
+/** Back `path` up to `<path>.bak` (or `.bak.N` when that is taken). Returns the backup path. */
+export declare function backupPath(path: string, exists: (p: string) => boolean): string;
+/** Apply a plan. Returns the manual steps still owed by the user. */
+export declare function applyPlan(actions: Action[], d: ApplyDeps): string[];
+/** The web app for a given API origin, when we can tell. */
+export declare function appUrlFor(server: string | undefined, explicit: string | undefined): string | undefined;
+/** Build a fresh single-profile `.taskflow.json` from a minted profile. */
+export declare function newConfig(server: string, project: number, profileName: string, profile: TaskflowConfig["profiles"][string]): TaskflowConfig;
+export interface Prompter {
+    ask(question: string): Promise<string>;
+    close(): void;
+}
+export interface InitDeps extends ApplyDeps {
+    plan: PlanEnv;
+    interactive: boolean;
+    prompter?: Prompter;
+    fetch?: FetchLike;
+    /** Runs the doctor from `dir`; returns its exit code. */
+    doctor(dir: string): Promise<number>;
+}
+/** Which harness CLIs / config dirs are present, for the default selection. */
+export declare function detectHarnesses(p: PlanEnv): Harness[];
+/**
+ * The walkthrough. Returns a process exit code: 0 when every registration went
+ * through (manual steps may remain), 1 on a usage error.
+ */
+export declare function runInit(argv: string[], deps: InitDeps): Promise<number>;
+/** Is `cmd` an executable on PATH? */
+export declare function onPath(cmd: string, env?: NodeJS.ProcessEnv): boolean;
+/** Wire {@link runInit} to the real machine and terminal. */
+export declare function runInitCommand(argv: string[]): Promise<number>;