@captainsafia/stitch 1.0.0-preview.c77f34b → 1.0.0-preview.f2fe33d

package/dist/api.d.ts

@@ -89,6 +89,70 @@ export declare class GitError extends StitchError {
 export declare class ValidationError extends StitchError {
 	constructor(message: string);
 }
+export declare class FinishForceRequiredError extends StitchError {
+	constructor(message: string);
+}
+export declare class InvalidSupersededByError extends StitchError {
+	constructor();
+}
+/**
+ * Terminal statuses that a stitch can be finished to
+ */
+export type TerminalStatus = "closed" | "superseded" | "abandoned";
+/**
+ * Options for finishing a stitch
+ */
+export interface FinishOptions {
+	/** Target status (default: "closed", may be auto-detected to "abandoned") */
+	status?: TerminalStatus;
+	/** For superseded status, the ID of the replacing stitch */
+	supersededBy?: StitchId;
+	/** Override auto-abandoned detection */
+	force?: boolean;
+	/** Skip confirmation for cascade closes (for non-interactive mode) */
+	skipConfirmation?: boolean;
+}
+/**
+ * Result of a finish operation
+ */
+export interface FinishResult {
+	/** All stitches that were finished */
+	finished: FinishedStitch[];
+	/** Warnings generated during the operation */
+	warnings: string[];
+	/** Whether auto-detection changed the status from the requested one */
+	autoDetectedStatus: boolean;
+	/** The final status applied */
+	finalStatus: TerminalStatus;
+}
+/**
+ * Information about a single finished stitch
+ */
+export interface FinishedStitch {
+	id: StitchId;
+	title: string;
+	previousStatus: StitchStatus;
+	newStatus: TerminalStatus;
+}
+/**
+ * Information needed before confirming a finish operation
+ */
+export interface FinishPreview {
+	/** The target stitch */
+	target: StitchDoc;
+	/** All stitches that will be affected (target + descendants) */
+	affected: StitchDoc[];
+	/** The final status that will be applied */
+	finalStatus: TerminalStatus;
+	/** Whether status was auto-detected */
+	autoDetected: boolean;
+	/** Warnings to show the user */
+	warnings: string[];
+	/** Whether confirmation is required (cascade affects 2+ stitches) */
+	requiresConfirmation: boolean;
+	/** Error if the operation cannot proceed without --force */
+	forceRequired?: string;
+}
 /**
  * StitchClient is the main public API for interacting with stitch.
  * CLI commands should use this class to perform all operations.
@@ -157,6 +221,30 @@ export declare class StitchClient {
 	 * Get stitch blame for a file
 	 */
 	blame(path: string): Promise<BlameLine[]>;
+	/**
+	 * Get direct children of a stitch
+	 */
+	getChildren(id: StitchId): Promise<StitchId[]>;
+	/**
+	 * Get all descendants (children, grandchildren, etc.) of a stitch
+	 */
+	getDescendants(id: StitchId): Promise<StitchId[]>;
+	/**
+	 * Prepare a finish operation without executing it.
+	 * Returns information needed to confirm or abort the operation.
+	 */
+	prepareFinish(id?: StitchId, options?: FinishOptions): Promise<FinishPreview>;
+	/**
+	 * Execute a prepared finish operation.
+	 * Clears the current stitch pointer after successful finish.
+	 */
+	executeFinish(preview: FinishPreview, options?: FinishOptions): Promise<FinishResult>;
+	/**
+	 * Finish a stitch (transition to terminal status).
+	 * High-level method that prepares and executes in one call.
+	 * Use prepareFinish + executeFinish separately when confirmation is needed.
+	 */
+	finish(id?: StitchId, options?: FinishOptions): Promise<FinishResult>;
 	/**
 	 * Dispose of the client (for using with `using` keyword)
 	 */