pm-orchestrator-runner 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pm-orchestrator-runner contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# PM Orchestrator Runner
+
+A CLI tool for orchestrated execution of Claude Code with evidence-based completion verification.
+
+## Features
+
+- Interactive REPL mode for Claude Code execution
+- Evidence-based completion tracking (prevents "fake completion" reports)
+- Two-stage timeout system (soft warning + hard terminate)
+- Session management and persistence
+- Non-interactive mode for scripting and automation
+
+## Installation
+
+```bash
+# Global installation
+npm install -g pm-orchestrator-runner
+
+# Or use npx
+npx pm-orchestrator-runner --help
+```
+
+## Quick Start
+
+### Interactive Mode
+
+```bash
+# Start REPL in current directory
+pm repl
+
+# Start REPL with specific project
+pm repl --project /path/to/project
+```
+
+### Non-Interactive Mode (Scripting)
+
+```bash
+# Pipe input
+echo "Create a file called hello.txt with content Hello World" | pm repl --non-interactive --exit-on-eof
+
+# Heredoc input
+pm repl --non-interactive --exit-on-eof << 'EOF'
+Create README.md with content "# My Project"
+EOF
+```
+
+### Fixed Project Mode
+
+For persistent verification root (useful for CI/CD):
+
+```bash
+pm repl --project-mode fixed --project-root /path/to/project
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `pm repl` | Start interactive REPL mode |
+| `pm start <path>` | Start a new session on a project |
+| `pm continue <id>` | Continue a paused session |
+| `pm status <id>` | Get session status |
+| `pm validate <path>` | Validate project structure |
+
+## REPL Options
+
+| Option | Description |
+|--------|-------------|
+| `--project <path>` | Project path (default: current directory) |
+| `--evidence <path>` | Evidence directory |
+| `--non-interactive` | Force non-interactive mode |
+| `--exit-on-eof` | Exit when EOF is received |
+| `--project-mode <mode>` | `temp` (default) or `fixed` |
+| `--project-root <path>` | Verification root directory |
+
+## REPL Commands
+
+Inside the REPL:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/status` | Show current session status |
+| `/tasks` | List all tasks |
+| `/logs [task-id]` | Show task logs |
+| `/session` | Show session info |
+| `/quit` | Exit REPL |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SOFT_TIMEOUT_MS` | Soft timeout in milliseconds (default: 60000) |
+| `HARD_TIMEOUT_MS` | Hard timeout in milliseconds (default: 120000) |
+| `CLI_TEST_MODE` | Set to `1` for test mode (mock executor) |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Claude Code CLI (`claude` command) installed
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.

package/dist/cli/cli-interface.d.ts

@@ -0,0 +1,150 @@
+/**
+ * CLI Interface for PM Orchestrator Runner
+ * Based on 05_CLI.md specification
+ */
+import { EventEmitter } from 'events';
+import { OverallStatus, LifecyclePhase } from '../models/enums';
+import { ErrorCode } from '../errors/error-codes';
+import { SessionStatus } from '../models/session';
+/**
+ * CLI Error class
+ */
+export declare class CLIError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: ErrorCode, message?: string, details?: Record<string, unknown>);
+}
+/**
+ * Parsed CLI arguments
+ */
+export interface ParsedArgs {
+    command?: string;
+    projectPath?: string;
+    sessionId?: string;
+    configPath?: string;
+    outputPath?: string;
+    verbose?: boolean;
+    quiet?: boolean;
+    dryRun?: boolean;
+    stream?: boolean;
+    format?: 'json' | 'compact';
+    help?: boolean;
+    version?: boolean;
+    limits?: {
+        max_files?: number;
+        max_tests?: number;
+        max_seconds?: number;
+    };
+}
+/**
+ * CLI run result
+ */
+export interface CLIResult {
+    session_id: string;
+    overall_status?: OverallStatus;
+    status?: SessionStatus;
+    current_phase?: LifecyclePhase;
+    tasks_completed?: number;
+    tasks_total?: number;
+    evidence?: Record<string, unknown>;
+    timestamp?: string;
+    resumed?: boolean;
+    interrupted?: boolean;
+    dry_run?: boolean;
+    would_execute?: boolean;
+    help?: string;
+    version?: string;
+}
+/**
+ * CLI options
+ */
+export interface CLIOptions {
+    evidenceDir: string;
+}
+/**
+ * Parse CLI arguments
+ */
+export declare function parseArgs(args: string[]): ParsedArgs;
+/**
+ * Validate parsed arguments
+ */
+export declare function validateArgs(args: ParsedArgs): ParsedArgs;
+/**
+ * CLI class
+ */
+export declare class CLI extends EventEmitter {
+    private readonly options;
+    private runner;
+    private currentSessionId;
+    private exitCode;
+    private verbose;
+    private quiet;
+    private interrupted;
+    private sessions;
+    constructor(options: CLIOptions);
+    /**
+     * Main run method
+     */
+    run(argv: string[]): Promise<CLIResult>;
+    /**
+     * Start command implementation (per spec 05_CLI.md L20-26)
+     */
+    private startCommand;
+    /**
+     * Continue command implementation
+     */
+    private continueCommand;
+    /**
+     * Status command implementation
+     */
+    private statusCommand;
+    /**
+     * Validate command implementation (per spec 05_CLI.md L20-26)
+     */
+    private validateCommand;
+    /**
+     * Run and format output as string
+     */
+    runAndFormat(argv: string[]): Promise<string>;
+    /**
+     * Pause a session
+     */
+    pauseSession(sessionId: string): void;
+    /**
+     * Complete a session
+     */
+    completeSession(sessionId: string): void;
+    /**
+     * Get exit code
+     */
+    getExitCode(): number;
+    /**
+     * Get exit code for a status
+     */
+    getExitCodeForStatus(status: OverallStatus): number;
+    /**
+     * Set verbose mode
+     */
+    setVerbose(flag: boolean): void;
+    /**
+     * Set quiet mode
+     */
+    setQuiet(flag: boolean): void;
+    /**
+     * Format error as JSON string
+     */
+    formatError(err: Error): string;
+    /**
+     * Handle signal
+     */
+    handleSignal(signal: string): void;
+    /**
+     * Get current session ID
+     */
+    getCurrentSessionId(): string | null;
+    /**
+     * Calculate progress percentage
+     */
+    private calculateProgress;
+}
+//# sourceMappingURL=cli-interface.d.ts.map

package/dist/cli/cli-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-interface.d.ts","sourceRoot":"","sources":["../../src/cli/cli-interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAKtC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,SAAS,EAAmB,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAMjF;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,aAAa,CAAC,EAAE,cAAc,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAYD;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA8DpD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CA6FzD;AAgDD;;GAEG;AACH,qBAAa,GAAI,SAAQ,YAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,QAAQ,CAA0E;gBAE9E,OAAO,EAAE,UAAU;IAK/B;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAqC7C;;OAEG;YACW,YAAY;IA+G1B;;OAEG;YACW,eAAe;IAoD7B;;OAEG;YACW,aAAa;IAwC3B;;OAEG;YACW,eAAe;IAmD7B;;OAEG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAWnD;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAgBxC;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM;IAiBnD;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAI/B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAI7B;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM;IAkB/B;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAWlC;;OAEG;IACH,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAIpC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAa1B"}