@p10i/rundown 1.0.0-rc.12

package/dist/index.d.ts

@@ -0,0 +1,397 @@
+/**
+ * Markdown AST-based task parser.
+ *
+ * Uses mdast to walk the parsed Markdown tree and extract task list items.
+ * Fenced code blocks and other non-task structures are naturally excluded
+ * by the AST — no regex guessing required.
+ */
+/** Represents a single task extracted from a Markdown document. */
+interface Task {
+    /** The text content of the task item. */
+    text: string;
+    /** Whether the checkbox is checked. */
+    checked: boolean;
+    /** Zero-based index among all tasks in the document. */
+    index: number;
+    /** 1-based line number in the source file. */
+    line: number;
+    /** Column offset of the checkbox in the source line. */
+    column: number;
+    /** Byte offset of the start of this node in the source. */
+    offsetStart: number;
+    /** Byte offset of the end of this node in the source. */
+    offsetEnd: number;
+    /** The source file path (set later by the caller). */
+    file: string;
+    /** Whether this is an inline CLI task (starts with "cli: "). */
+    isInlineCli: boolean;
+    /** If inline CLI, the command string. */
+    cliCommand?: string;
+    /** Nesting depth (0 = top-level list item). */
+    depth: number;
+}
+
+/**
+ * File sorting.
+ *
+ * Provides sorting strategies for resolved Markdown file paths.
+ */
+type SortMode = "name-sort" | "none" | "old-first" | "new-first";
+
+interface FileSystemStat {
+    isFile: boolean;
+    isDirectory: boolean;
+    birthtimeMs?: number;
+    mtimeMs?: number;
+}
+interface FileSystemDirent {
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+}
+interface FileSystem {
+    exists(path: string): boolean;
+    readText(filePath: string): string;
+    writeText(filePath: string, content: string): void;
+    mkdir(dirPath: string, options?: {
+        recursive?: boolean;
+    }): void;
+    readdir(dirPath: string): FileSystemDirent[];
+    stat(path: string): FileSystemStat | null;
+    unlink(filePath: string): void;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): void;
+}
+
+type ProcessRunMode = "wait" | "tui" | "detached";
+interface ProcessRunOptions {
+    command: string;
+    args: string[];
+    cwd: string;
+    mode: ProcessRunMode;
+    shell?: boolean;
+    env?: Record<string, string | undefined>;
+    timeoutMs?: number;
+}
+interface ProcessRunResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+interface ProcessRunner {
+    run(options: ProcessRunOptions): Promise<ProcessRunResult>;
+}
+
+interface GitClient {
+    run(args: string[], cwd: string, options?: {
+        timeoutMs?: number;
+    }): Promise<string>;
+}
+
+interface TemplateLoader {
+    load(filePath: string): string | null;
+}
+
+interface ValidationSidecar {
+    filePath(task: Task): string;
+    read(task: Task): string | null;
+    remove(task: Task): void;
+}
+
+type ArtifactStoreStatus = "running" | "completed" | "failed" | "detached" | string;
+type ArtifactStorePhase = "execute" | "verify" | "repair" | "plan" | "inline-cli" | "worker";
+interface ArtifactTaskMetadata {
+    text: string;
+    file: string;
+    line: number;
+    index: number;
+    source: string;
+}
+interface ArtifactRunContext {
+    runId: string;
+    rootDir: string;
+    cwd: string;
+    keepArtifacts: boolean;
+    commandName: string;
+    workerCommand?: string[];
+    mode?: string;
+    transport?: string;
+    task?: ArtifactTaskMetadata;
+}
+interface ArtifactPhaseHandle {
+    context: ArtifactRunContext;
+    phase: ArtifactStorePhase;
+    sequence: number;
+    dir: string;
+    promptFile: string | null;
+}
+interface ArtifactRunMetadata {
+    runId: string;
+    rootDir: string;
+    relativePath: string;
+    commandName: string;
+    workerCommand?: string[];
+    mode?: string;
+    transport?: string;
+    source?: string;
+    task?: ArtifactTaskMetadata;
+    keepArtifacts: boolean;
+    startedAt: string;
+    completedAt?: string;
+    status?: string;
+}
+interface ArtifactStore {
+    createContext(options: {
+        cwd?: string;
+        commandName: string;
+        workerCommand?: string[];
+        mode?: string;
+        transport?: string;
+        source?: string;
+        task?: ArtifactTaskMetadata;
+        keepArtifacts?: boolean;
+    }): ArtifactRunContext;
+    beginPhase(context: ArtifactRunContext, options: {
+        phase: ArtifactStorePhase;
+        prompt?: string;
+        command?: string[];
+        mode?: string;
+        transport?: string;
+        notes?: string;
+        extra?: Record<string, unknown>;
+    }): ArtifactPhaseHandle;
+    completePhase(handle: ArtifactPhaseHandle, options: {
+        exitCode: number | null;
+        stdout?: string;
+        stderr?: string;
+        outputCaptured: boolean;
+        notes?: string;
+        extra?: Record<string, unknown>;
+    }): void;
+    finalize(context: ArtifactRunContext, options: {
+        status: ArtifactStoreStatus;
+        preserve?: boolean;
+    }): void;
+    displayPath(context: ArtifactRunContext): string;
+    rootDir(cwd?: string): string;
+    listSaved(cwd?: string): ArtifactRunMetadata[];
+    listFailed(cwd?: string): ArtifactRunMetadata[];
+    latest(cwd?: string): ArtifactRunMetadata | null;
+    find(runId: string, cwd?: string): ArtifactRunMetadata | null;
+    removeSaved(cwd?: string): number;
+    removeFailed(cwd?: string): number;
+    isFailedStatus(status: string | undefined): boolean;
+}
+
+interface Clock {
+    now(): Date;
+    nowIsoString(): string;
+}
+
+type ApplicationOutputEvent = {
+    kind: "info";
+    message: string;
+} | {
+    kind: "warn";
+    message: string;
+} | {
+    kind: "error";
+    message: string;
+} | {
+    kind: "success";
+    message: string;
+} | {
+    kind: "task";
+    task: Task;
+    blocked?: boolean;
+} | {
+    kind: "text";
+    text: string;
+} | {
+    kind: "stderr";
+    text: string;
+};
+interface ApplicationOutputPort {
+    emit(event: ApplicationOutputEvent): void;
+}
+
+interface SourceResolverPort {
+    resolveSources(source: string): Promise<string[]>;
+}
+
+interface TaskSelectionResult {
+    task: Task;
+    source: string;
+    contextBefore: string;
+}
+interface TaskSelectorPort {
+    selectNextTask(files: string[], sortMode: SortMode): TaskSelectionResult | null;
+    selectTaskByLocation(filePath: string, line: number): TaskSelectionResult | null;
+}
+
+type PromptTransport$2 = "file" | "arg";
+interface WorkerRunResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+interface WorkerExecutionOptions {
+    command: string[];
+    prompt: string;
+    mode: ProcessRunMode;
+    transport: PromptTransport$2;
+    cwd: string;
+    artifactContext?: unknown;
+    artifactPhase?: "execute" | "verify" | "repair" | "worker" | "plan";
+    artifactExtra?: Record<string, unknown>;
+}
+interface InlineCliExecutionOptions {
+    artifactContext?: unknown;
+    keepArtifacts?: boolean;
+    artifactExtra?: Record<string, unknown>;
+}
+interface WorkerExecutorPort {
+    runWorker(options: WorkerExecutionOptions): Promise<WorkerRunResult>;
+    executeInlineCli(command: string, cwd: string, options?: InlineCliExecutionOptions): Promise<WorkerRunResult>;
+}
+
+interface TaskValidationOptions {
+    task: Task;
+    source: string;
+    contextBefore: string;
+    template: string;
+    command: string[];
+    mode?: ProcessRunMode;
+    transport?: PromptTransport$2;
+    cwd?: string;
+    templateVars?: Record<string, unknown>;
+    artifactContext?: unknown;
+}
+interface TaskValidationPort {
+    validate(options: TaskValidationOptions): Promise<boolean>;
+}
+
+interface TaskCorrectionOptions {
+    task: Task;
+    source: string;
+    contextBefore: string;
+    correctTemplate: string;
+    validateTemplate: string;
+    command: string[];
+    maxRetries: number;
+    mode?: ProcessRunMode;
+    transport?: PromptTransport$2;
+    cwd?: string;
+    templateVars?: Record<string, unknown>;
+    artifactContext?: unknown;
+}
+interface TaskCorrectionResult {
+    valid: boolean;
+    attempts: number;
+}
+interface TaskCorrectionPort {
+    correct(options: TaskCorrectionOptions): Promise<TaskCorrectionResult>;
+}
+
+interface WorkingDirectoryPort {
+    cwd(): string;
+}
+
+interface DirectoryOpenerPort {
+    openDirectory(dirPath: string): void;
+}
+
+type RunnerMode$1 = ProcessRunMode;
+type PromptTransport$1 = PromptTransport$2;
+interface RunTaskOptions {
+    source: string;
+    mode: RunnerMode$1;
+    transport: PromptTransport$1;
+    sortMode: SortMode;
+    verify: boolean;
+    onlyVerify: boolean;
+    noRepair: boolean;
+    retries: number;
+    dryRun: boolean;
+    printPrompt: boolean;
+    keepArtifacts: boolean;
+    varsFileOption: string | boolean | undefined;
+    cliTemplateVarArgs: string[];
+    workerCommand: string[];
+    commitAfterComplete: boolean;
+    commitMessageTemplate?: string;
+    onCompleteCommand?: string;
+}
+
+type RunnerMode = ProcessRunMode;
+type PromptTransport = "file" | "arg";
+interface PlanTaskOptions {
+    source: string;
+    at?: string;
+    mode: RunnerMode;
+    transport: PromptTransport;
+    sortMode: SortMode;
+    dryRun: boolean;
+    printPrompt: boolean;
+    keepArtifacts: boolean;
+    varsFileOption: string | boolean | undefined;
+    cliTemplateVarArgs: string[];
+    workerCommand: string[];
+}
+
+interface ListTasksOptions {
+    source: string;
+    sortMode: SortMode;
+    includeAll: boolean;
+}
+
+interface NextTaskOptions {
+    source: string;
+    sortMode: SortMode;
+}
+
+interface ManageArtifactsOptions {
+    clean: boolean;
+    json: boolean;
+    failed: boolean;
+    open: string;
+    cwd?: string;
+}
+
+type App = {
+    runTask: (options: RunTaskOptions) => Promise<number>;
+    planTask: (options: PlanTaskOptions) => Promise<number>;
+    listTasks: (options: ListTasksOptions) => Promise<number>;
+    nextTask: (options: NextTaskOptions) => Promise<number>;
+    initProject: () => Promise<number>;
+    manageArtifacts: (options: ManageArtifactsOptions) => number;
+};
+type AppUseCaseFactories = {
+    [Key in keyof App]: (ports: AppPorts) => App[Key];
+};
+interface AppPorts {
+    fileSystem: FileSystem;
+    processRunner: ProcessRunner;
+    gitClient: GitClient;
+    templateLoader: TemplateLoader;
+    validationSidecar: ValidationSidecar;
+    artifactStore: ArtifactStore;
+    clock: Clock;
+    directoryOpener: DirectoryOpenerPort;
+    sourceResolver: SourceResolverPort;
+    taskSelector: TaskSelectorPort;
+    workerExecutor: WorkerExecutorPort;
+    taskValidation: TaskValidationPort;
+    taskCorrection: TaskCorrectionPort;
+    workingDirectory: WorkingDirectoryPort;
+    output: ApplicationOutputPort;
+}
+interface CreateAppDependencies {
+    ports?: Partial<AppPorts>;
+    useCaseFactories?: Partial<AppUseCaseFactories>;
+}
+declare function createApp(dependencies?: CreateAppDependencies): App;
+
+export { type App, type AppPorts, type AppUseCaseFactories, type CreateAppDependencies, createApp };