dev-sesssion 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,333 @@
+import { Command } from 'commander';
+
+/**
+ * Commander program setup for the dev-session CLI.
+ *
+ * Defines the root program with global options and registers all
+ * subcommands. This module owns the Commander instance — `index.ts`
+ * imports and runs it.
+ *
+ * @module
+ */
+
+/**
+ * Create and configure the Commander program.
+ *
+ * @returns The configured Commander program (not yet parsed)
+ */
+declare function createProgram(): Command;
+/**
+ * Parse arguments and run the CLI.
+ *
+ * Installs signal handlers, creates the program, parses argv,
+ * and handles any uncaught errors.
+ *
+ * @param argv - Process arguments (defaults to process.argv)
+ * @returns Promise that resolves when the command completes
+ */
+declare function run(argv?: readonly string[]): Promise<void>;
+
+/**
+ * `dev-session advance` command.
+ *
+ * Archives the current chunk, compacts session state, advances to the
+ * next chunk, and regenerates NEXT_PROMPT.md. Warns if not all tasks in
+ * the active chunk are done, prompting for confirmation to force-advance.
+ *
+ * Business logic lives in @dev-session/core — this module handles CLI
+ * prompts, formatting, and orchestration.
+ *
+ * @module
+ */
+
+/** Options passed from Commander to the advance action. */
+interface AdvanceOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Skip prompts and force-advance even with incomplete tasks. */
+    readonly yes: boolean;
+    /** Show detailed output. */
+    readonly verbose: boolean;
+    /** Explicit adapter override (from --adapter flag). */
+    readonly adapter?: string;
+}
+/** Result returned after an advance run. */
+interface AdvanceResult {
+    /** The chunk ID that was archived. */
+    readonly archivedChunkId: number;
+    /** The new active chunk ID. */
+    readonly newChunkId: number;
+    /** Title of the new active chunk. */
+    readonly newChunkTitle: string;
+    /** Number of tasks remaining in the new chunk. */
+    readonly tasksRemaining: number;
+    /** Whether a force-advance was needed (incomplete tasks). */
+    readonly forceAdvanced: boolean;
+}
+
+/**
+ * `dev-session index` commands: `add` and `audit`.
+ *
+ * - `add <filepath>` — validate and append a file to FILE_INDEX.md
+ * - `audit` — detect stale entries and optionally auto-remove them
+ *
+ * Business logic lives in @dev-session/core — this module handles CLI
+ * prompts, formatting, and Commander registration.
+ *
+ * @module
+ */
+
+/** Options for the index add subcommand. */
+interface IndexAddOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** The file path to add. */
+    readonly filepath: string;
+    /** Skip prompts and use defaults. */
+    readonly yes: boolean;
+    /** Show detailed output. */
+    readonly verbose: boolean;
+}
+/** Options for the index audit subcommand. */
+interface IndexAuditOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Automatically remove stale entries after confirmation. */
+    readonly fix: boolean;
+    /** Skip prompts (auto-confirm removals). */
+    readonly yes: boolean;
+    /** Show detailed output. */
+    readonly verbose: boolean;
+}
+
+/**
+ * `dev-session init` command.
+ *
+ * Orchestrates the full init wizard: detection, migration path selection,
+ * plan splitting or scaffolding, FILE_INDEX generation, and final writes.
+ *
+ * Business logic lives in @dev-session/core -- this module only handles
+ * CLI prompts, formatting, and file write orchestration.
+ *
+ * @module
+ */
+
+/** Options passed from commander to the init action. */
+interface InitOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Skip all prompts and use defaults. */
+    readonly yes: boolean;
+    /** Log writes without touching the filesystem. */
+    readonly dryRun: boolean;
+    /** Show verbose output. */
+    readonly verbose: boolean;
+    /** Enable strict mode (block on secret detection). */
+    readonly strict: boolean;
+    /** Explicit adapter override (from --adapter flag). */
+    readonly adapter?: string;
+    /**
+     * Explicitly enable team mode (auto-applies .gitignore + .gitattributes).
+     * When undefined and not --yes, the wizard prompts for team vs personal.
+     */
+    readonly teamMode?: boolean;
+    /**
+     * Cap the number of files indexed during FILE_INDEX generation.
+     * When undefined, all discovered files are indexed.
+     */
+    readonly maxFiles?: number;
+}
+
+/**
+ * `dev-session prompt` command.
+ *
+ * Prints the contents of NEXT_PROMPT.md to stdout for piping or copying.
+ * Supports a `--copy` flag that copies to the system clipboard using
+ * platform-native commands (pbcopy on macOS, xclip/xsel on Linux,
+ * clip.exe on Windows).
+ *
+ * @module
+ */
+
+/** Options passed from Commander to the prompt action. */
+interface PromptOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Copy prompt to system clipboard. */
+    readonly copy: boolean;
+}
+
+/**
+ * `dev-session status` command.
+ *
+ * Reads the session state, active plan chunk, and file index to display
+ * a rich status overview: task completion percentage, context budget
+ * breakdown, health warnings, and optional JSON output.
+ *
+ * Business logic lives in @dev-session/core — this module handles CLI
+ * display formatting and Commander registration.
+ *
+ * @module
+ */
+
+/** Options passed from Commander to the status action. */
+interface StatusOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Output machine-readable JSON. */
+    readonly json: boolean;
+    /** Show verbose output. */
+    readonly verbose: boolean;
+}
+/** JSON-serializable status output for --json flag. */
+interface StatusJson {
+    readonly active_chunk: number;
+    readonly chunk_title: string;
+    readonly session_id: string;
+    readonly last_updated: string;
+    readonly tasks: {
+        readonly total: number;
+        readonly done: number;
+        readonly in_progress: number;
+        readonly todo: number;
+        readonly percent_complete: number;
+    };
+    readonly files: {
+        readonly always_include: number;
+        readonly indexed: number;
+        readonly context: number;
+    };
+    readonly budget: {
+        readonly total_tokens: number;
+        readonly budget_cap: number;
+        readonly over_budget: boolean;
+        readonly accurate: boolean;
+    };
+    readonly warnings: readonly string[];
+    readonly days_since_last_session: number | null;
+}
+
+/**
+ * `dev-session update` command.
+ *
+ * Interactive task marking, note adding, "last worked" file updates,
+ * prompt regeneration, and secret scanning. In `--yes` mode, only
+ * auto-detectable updates are applied (git status for last-worked files).
+ *
+ * Business logic lives in @dev-session/core — this module handles CLI
+ * prompts, formatting, and file write orchestration.
+ *
+ * @module
+ */
+
+/** Options passed from Commander to the update action. */
+interface UpdateOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Skip prompts and apply auto-detectable updates only. */
+    readonly yes: boolean;
+    /** Show detailed output. */
+    readonly verbose: boolean;
+    /** Enable strict mode (block on secret detection). */
+    readonly strict: boolean;
+    /** Explicit adapter override (from --adapter flag). */
+    readonly adapter?: string;
+}
+/** Result returned after an update run. */
+interface UpdateResult {
+    /** Number of tasks whose status was changed. */
+    readonly tasksUpdated: number;
+    /** Number of notes added. */
+    readonly notesAdded: number;
+    /** Whether the last-worked file list was changed. */
+    readonly lastWorkedUpdated: boolean;
+    /** Whether NEXT_PROMPT.md was regenerated. */
+    readonly promptRegenerated: boolean;
+    /** Number of secret scan warnings found. */
+    readonly secretWarnings: number;
+}
+
+/**
+ * Dry-run file write proxy.
+ *
+ * When `--dry-run` is active, replaces actual file writes with log output
+ * showing what would be written. All methods mirror the AtomicWriter API
+ * but only log — no filesystem changes.
+ *
+ * @module
+ */
+/**
+ * Log what a file write would produce without actually writing.
+ *
+ * @param filePath - The target file path
+ * @param content - The content that would be written
+ * @param cwd - The working directory (for relative path display)
+ */
+declare function dryRunWrite(filePath: string, content: string, cwd: string): void;
+/**
+ * Log what a directory creation would produce without actually creating.
+ *
+ * @param dirPath - The target directory path
+ * @param cwd - The working directory (for relative path display)
+ */
+declare function dryRunMkdir(dirPath: string, cwd: string): void;
+/**
+ * Log what a .gitignore patch would produce without actually patching.
+ *
+ * @param filePath - The .gitignore file path
+ * @param entries - Lines that would be appended
+ * @param cwd - The working directory (for relative path display)
+ */
+declare function dryRunGitignorePatch(filePath: string, entries: readonly string[], cwd: string): void;
+
+/**
+ * Global error handler for the dev-session CLI.
+ *
+ * Catches typed errors (CliError, ParseError, SecurityError) and formats
+ * them for terminal output. Unrecognized errors get a generic message.
+ *
+ * @module
+ */
+/**
+ * Format and display an error in the terminal, then exit with the
+ * appropriate code.
+ *
+ * @param error - The caught error (typed or unknown)
+ * @param opts - Options controlling exit behavior
+ * @param opts.exit - Whether to call process.exit (default: true). Set to false in tests.
+ * @returns The exit code that was (or would be) used
+ */
+declare function handleError(error: unknown, opts?: {
+    exit?: boolean;
+}): number;
+
+/**
+ * Signal handler for graceful cleanup on SIGINT/SIGTERM.
+ *
+ * Registers cleanup callbacks that run when the process receives an
+ * interrupt or termination signal. Uses a re-entrancy guard to prevent
+ * double-cleanup. Cleans up partial `.tmp` files from AtomicWriter.
+ *
+ * @module
+ */
+/** Cleanup callback type. */
+type CleanupFn = () => void | Promise<void>;
+/**
+ * Register a cleanup function to run on signal.
+ *
+ * @param fn - Synchronous or async cleanup callback
+ * @returns A dispose function that unregisters the callback
+ */
+declare function onCleanup(fn: CleanupFn): () => void;
+/**
+ * Install SIGINT and SIGTERM handlers.
+ *
+ * Should be called once at CLI startup. Handlers run cleanup functions,
+ * print a cancellation message, and exit with code 130 (SIGINT) or
+ * 143 (SIGTERM).
+ *
+ * @returns A dispose function that removes the handlers
+ */
+declare function installSignalHandlers(): () => void;
+
+export { type AdvanceOptions, type AdvanceResult, type IndexAddOptions, type IndexAuditOptions, type InitOptions, type PromptOptions, type StatusJson, type StatusOptions, type UpdateOptions, type UpdateResult, createProgram, dryRunGitignorePatch, dryRunMkdir, dryRunWrite, handleError, installSignalHandlers, onCleanup, run };

package/dist/index.d.ts

@@ -0,0 +1,333 @@
+import { Command } from 'commander';
+
+/**
+ * Commander program setup for the dev-session CLI.
+ *
+ * Defines the root program with global options and registers all
+ * subcommands. This module owns the Commander instance — `index.ts`
+ * imports and runs it.
+ *
+ * @module
+ */
+
+/**
+ * Create and configure the Commander program.
+ *
+ * @returns The configured Commander program (not yet parsed)
+ */
+declare function createProgram(): Command;
+/**
+ * Parse arguments and run the CLI.
+ *
+ * Installs signal handlers, creates the program, parses argv,
+ * and handles any uncaught errors.
+ *
+ * @param argv - Process arguments (defaults to process.argv)
+ * @returns Promise that resolves when the command completes
+ */
+declare function run(argv?: readonly string[]): Promise<void>;
+
+/**
+ * `dev-session advance` command.
+ *
+ * Archives the current chunk, compacts session state, advances to the
+ * next chunk, and regenerates NEXT_PROMPT.md. Warns if not all tasks in
+ * the active chunk are done, prompting for confirmation to force-advance.
+ *
+ * Business logic lives in @dev-session/core — this module handles CLI
+ * prompts, formatting, and orchestration.
+ *
+ * @module
+ */
+
+/** Options passed from Commander to the advance action. */
+interface AdvanceOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Skip prompts and force-advance even with incomplete tasks. */
+    readonly yes: boolean;
+    /** Show detailed output. */
+    readonly verbose: boolean;
+    /** Explicit adapter override (from --adapter flag). */
+    readonly adapter?: string;
+}
+/** Result returned after an advance run. */
+interface AdvanceResult {
+    /** The chunk ID that was archived. */
+    readonly archivedChunkId: number;
+    /** The new active chunk ID. */
+    readonly newChunkId: number;
+    /** Title of the new active chunk. */
+    readonly newChunkTitle: string;
+    /** Number of tasks remaining in the new chunk. */
+    readonly tasksRemaining: number;
+    /** Whether a force-advance was needed (incomplete tasks). */
+    readonly forceAdvanced: boolean;
+}
+
+/**
+ * `dev-session index` commands: `add` and `audit`.
+ *
+ * - `add <filepath>` — validate and append a file to FILE_INDEX.md
+ * - `audit` — detect stale entries and optionally auto-remove them
+ *
+ * Business logic lives in @dev-session/core — this module handles CLI
+ * prompts, formatting, and Commander registration.
+ *
+ * @module
+ */
+
+/** Options for the index add subcommand. */
+interface IndexAddOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** The file path to add. */
+    readonly filepath: string;
+    /** Skip prompts and use defaults. */
+    readonly yes: boolean;
+    /** Show detailed output. */
+    readonly verbose: boolean;
+}
+/** Options for the index audit subcommand. */
+interface IndexAuditOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Automatically remove stale entries after confirmation. */
+    readonly fix: boolean;
+    /** Skip prompts (auto-confirm removals). */
+    readonly yes: boolean;
+    /** Show detailed output. */
+    readonly verbose: boolean;
+}
+
+/**
+ * `dev-session init` command.
+ *
+ * Orchestrates the full init wizard: detection, migration path selection,
+ * plan splitting or scaffolding, FILE_INDEX generation, and final writes.
+ *
+ * Business logic lives in @dev-session/core -- this module only handles
+ * CLI prompts, formatting, and file write orchestration.
+ *
+ * @module
+ */
+
+/** Options passed from commander to the init action. */
+interface InitOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Skip all prompts and use defaults. */
+    readonly yes: boolean;
+    /** Log writes without touching the filesystem. */
+    readonly dryRun: boolean;
+    /** Show verbose output. */
+    readonly verbose: boolean;
+    /** Enable strict mode (block on secret detection). */
+    readonly strict: boolean;
+    /** Explicit adapter override (from --adapter flag). */
+    readonly adapter?: string;
+    /**
+     * Explicitly enable team mode (auto-applies .gitignore + .gitattributes).
+     * When undefined and not --yes, the wizard prompts for team vs personal.
+     */
+    readonly teamMode?: boolean;
+    /**
+     * Cap the number of files indexed during FILE_INDEX generation.
+     * When undefined, all discovered files are indexed.
+     */
+    readonly maxFiles?: number;
+}
+
+/**
+ * `dev-session prompt` command.
+ *
+ * Prints the contents of NEXT_PROMPT.md to stdout for piping or copying.
+ * Supports a `--copy` flag that copies to the system clipboard using
+ * platform-native commands (pbcopy on macOS, xclip/xsel on Linux,
+ * clip.exe on Windows).
+ *
+ * @module
+ */
+
+/** Options passed from Commander to the prompt action. */
+interface PromptOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Copy prompt to system clipboard. */
+    readonly copy: boolean;
+}
+
+/**
+ * `dev-session status` command.
+ *
+ * Reads the session state, active plan chunk, and file index to display
+ * a rich status overview: task completion percentage, context budget
+ * breakdown, health warnings, and optional JSON output.
+ *
+ * Business logic lives in @dev-session/core — this module handles CLI
+ * display formatting and Commander registration.
+ *
+ * @module
+ */
+
+/** Options passed from Commander to the status action. */
+interface StatusOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Output machine-readable JSON. */
+    readonly json: boolean;
+    /** Show verbose output. */
+    readonly verbose: boolean;
+}
+/** JSON-serializable status output for --json flag. */
+interface StatusJson {
+    readonly active_chunk: number;
+    readonly chunk_title: string;
+    readonly session_id: string;
+    readonly last_updated: string;
+    readonly tasks: {
+        readonly total: number;
+        readonly done: number;
+        readonly in_progress: number;
+        readonly todo: number;
+        readonly percent_complete: number;
+    };
+    readonly files: {
+        readonly always_include: number;
+        readonly indexed: number;
+        readonly context: number;
+    };
+    readonly budget: {
+        readonly total_tokens: number;
+        readonly budget_cap: number;
+        readonly over_budget: boolean;
+        readonly accurate: boolean;
+    };
+    readonly warnings: readonly string[];
+    readonly days_since_last_session: number | null;
+}
+
+/**
+ * `dev-session update` command.
+ *
+ * Interactive task marking, note adding, "last worked" file updates,
+ * prompt regeneration, and secret scanning. In `--yes` mode, only
+ * auto-detectable updates are applied (git status for last-worked files).
+ *
+ * Business logic lives in @dev-session/core — this module handles CLI
+ * prompts, formatting, and file write orchestration.
+ *
+ * @module
+ */
+
+/** Options passed from Commander to the update action. */
+interface UpdateOptions {
+    /** Working directory override. */
+    readonly cwd: string;
+    /** Skip prompts and apply auto-detectable updates only. */
+    readonly yes: boolean;
+    /** Show detailed output. */
+    readonly verbose: boolean;
+    /** Enable strict mode (block on secret detection). */
+    readonly strict: boolean;
+    /** Explicit adapter override (from --adapter flag). */
+    readonly adapter?: string;
+}
+/** Result returned after an update run. */
+interface UpdateResult {
+    /** Number of tasks whose status was changed. */
+    readonly tasksUpdated: number;
+    /** Number of notes added. */
+    readonly notesAdded: number;
+    /** Whether the last-worked file list was changed. */
+    readonly lastWorkedUpdated: boolean;
+    /** Whether NEXT_PROMPT.md was regenerated. */
+    readonly promptRegenerated: boolean;
+    /** Number of secret scan warnings found. */
+    readonly secretWarnings: number;
+}
+
+/**
+ * Dry-run file write proxy.
+ *
+ * When `--dry-run` is active, replaces actual file writes with log output
+ * showing what would be written. All methods mirror the AtomicWriter API
+ * but only log — no filesystem changes.
+ *
+ * @module
+ */
+/**
+ * Log what a file write would produce without actually writing.
+ *
+ * @param filePath - The target file path
+ * @param content - The content that would be written
+ * @param cwd - The working directory (for relative path display)
+ */
+declare function dryRunWrite(filePath: string, content: string, cwd: string): void;
+/**
+ * Log what a directory creation would produce without actually creating.
+ *
+ * @param dirPath - The target directory path
+ * @param cwd - The working directory (for relative path display)
+ */
+declare function dryRunMkdir(dirPath: string, cwd: string): void;
+/**
+ * Log what a .gitignore patch would produce without actually patching.
+ *
+ * @param filePath - The .gitignore file path
+ * @param entries - Lines that would be appended
+ * @param cwd - The working directory (for relative path display)
+ */
+declare function dryRunGitignorePatch(filePath: string, entries: readonly string[], cwd: string): void;
+
+/**
+ * Global error handler for the dev-session CLI.
+ *
+ * Catches typed errors (CliError, ParseError, SecurityError) and formats
+ * them for terminal output. Unrecognized errors get a generic message.
+ *
+ * @module
+ */
+/**
+ * Format and display an error in the terminal, then exit with the
+ * appropriate code.
+ *
+ * @param error - The caught error (typed or unknown)
+ * @param opts - Options controlling exit behavior
+ * @param opts.exit - Whether to call process.exit (default: true). Set to false in tests.
+ * @returns The exit code that was (or would be) used
+ */
+declare function handleError(error: unknown, opts?: {
+    exit?: boolean;
+}): number;
+
+/**
+ * Signal handler for graceful cleanup on SIGINT/SIGTERM.
+ *
+ * Registers cleanup callbacks that run when the process receives an
+ * interrupt or termination signal. Uses a re-entrancy guard to prevent
+ * double-cleanup. Cleans up partial `.tmp` files from AtomicWriter.
+ *
+ * @module
+ */
+/** Cleanup callback type. */
+type CleanupFn = () => void | Promise<void>;
+/**
+ * Register a cleanup function to run on signal.
+ *
+ * @param fn - Synchronous or async cleanup callback
+ * @returns A dispose function that unregisters the callback
+ */
+declare function onCleanup(fn: CleanupFn): () => void;
+/**
+ * Install SIGINT and SIGTERM handlers.
+ *
+ * Should be called once at CLI startup. Handlers run cleanup functions,
+ * print a cancellation message, and exit with code 130 (SIGINT) or
+ * 143 (SIGTERM).
+ *
+ * @returns A dispose function that removes the handlers
+ */
+declare function installSignalHandlers(): () => void;
+
+export { type AdvanceOptions, type AdvanceResult, type IndexAddOptions, type IndexAuditOptions, type InitOptions, type PromptOptions, type StatusJson, type StatusOptions, type UpdateOptions, type UpdateResult, createProgram, dryRunGitignorePatch, dryRunMkdir, dryRunWrite, handleError, installSignalHandlers, onCleanup, run };