@hoplogic/hopjit 0.1.0

package/dist/cli-types.d.ts

@@ -0,0 +1,190 @@
+import type { OutputDecl, StepSummary, ExecutableStepType, ResponseOption } from './ast-types.js';
+import type { AssembledContext, RetryRecord } from './runtime-types.js';
+import type { SpecError, ErrorCode } from './errors.js';
+/** hopjit init 响应联合：成功创建实例或校验失败。见 [[hop-cli#^anc-cli-init-response]] */
+export type InitResponse = InitSuccess | InitError;
+/** init 成功：实例已创建，warn 级校验结果透传供作者修复。见 [[hop-cli#^anc-cli-init-response]] */
+export interface InitSuccess {
+    status: 'ok';
+    instance_id: string;
+    warnings?: SpecError[];
+}
+/** init 失败：error 级解析或校验违规阻断，不创建实例。见 [[hop-cli#^anc-cli-init-response]] */
+export interface InitError {
+    status: 'error';
+    errors: SpecError[];
+}
+export interface ValidateResponse {
+    status: 'ok' | 'error';
+    errors: SpecError[];
+    warnings: SpecError[];
+}
+export interface ListResponse {
+    status: 'ok';
+    dir: string;
+    specs: Array<{
+        file: string;
+        id: string;
+        goal: string;
+    }>;
+}
+/** hopjit next 推进响应联合，6 形态由 status 区分（parallel_ready 仅复用模式真并行）。见 [[hop-cli#^anc-cli-next-response]] */
+export type NextResponse = StepReady | AdaptiveNeeded | ExecutionCompleted | ExecutionFailed | ExecutionPaused | ParallelReady;
+/** agent 主循环的正常推进信号：返回待执行步骤及其装配上下文。见 [[hop-cli#^anc-cli-step-ready]] */
+export interface StepReady {
+    status: 'step_ready';
+    instance_id: string;
+    step_id: string;
+    step_type: ExecutableStepType;
+    summary: string;
+    context: AssembledContext;
+    work_zone: string;
+    output_path: string;
+}
+export interface ParallelReady {
+    status: 'parallel_ready';
+    instance_id: string;
+    parallel_step_id: string;
+    children: ParallelChildSpec[];
+    max_concurrent: number;
+    parent_log_dir?: string;
+    work_zone: string;
+}
+/** fan-out CLI 调度顾问（fanout-plan/fanout-next）的返回：下一步调度动作。
+ * 主 agent 是句柄执行器（起 worker/收通知），CLI 无状态算调度决策。
+ * 见 design/parallel-execution.md ^anc-exec-parallel-fanout-advisor。 // @a: anc-exec-parallel-fanout-advisor */
+export type FanoutScheduleResult = {
+    action: 'launch';
+    max_concurrent: number;
+    workers: FanoutWorker[];
+    remaining: string[];
+} | {
+    action: 'join';
+    command: string;
+} | {
+    action: 'wait';
+    running: string[];
+} | {
+    action: 'error';
+    message: string;
+};
+/** 待起 worker：child 步骤 ID + CLI 拼好的完整启动命令（含 cd 锁 cwd、run 参数、log-dir；不含 --params）。 */
+export interface FanoutWorker {
+    child_step_id: string;
+    launch_command: string;
+}
+/** 单个待并发 child 容器规格：步骤 ID、子实例目录及引擎自动解析的入参。见 [[hop-cli#^anc-types-parallel-ready]] */
+export interface ParallelChildSpec {
+    child_step_id: string;
+    summary: string;
+    subinstance_dir: string;
+    params_for_child: Record<string, unknown>;
+}
+/** subtask 重试耗尽需重规划信号：携交付契约、原 children 与重试历史供 replan。见 [[hop-cli#^anc-cli-next-response]] */
+export interface AdaptiveNeeded {
+    status: 'adaptive_needed';
+    instance_id: string;
+    spec_id: string;
+    subtask_id: string;
+    failure: {
+        step_id: string;
+        reason: string;
+        attempt: number;
+        max_retries: number;
+    };
+    subtask_contract: {
+        outputs: OutputDecl[];
+        constraints: string[];
+    };
+    original_children: StepSummary[];
+    retry_history: RetryRecord[];
+}
+export interface ReplanAudit {
+    spec_id: string;
+    step_id: string;
+    error_reason: string;
+    generated_children: StepSummary[];
+    base: 'scratch' | 'fallback';
+    at: string;
+}
+/** 执行成功终态：返回全部 outputs（大值可能为 $file 指针）。见 [[hop-cli#^anc-cli-next-response]] */
+export interface ExecutionCompleted {
+    status: 'completed';
+    instance_id: string;
+    outputs: Record<string, unknown>;
+    work_zone: string;
+}
+/** 执行失败终态：给出失败步骤、原因与含 null 的部分产物。见 [[hop-cli#^anc-cli-next-response]] */
+export interface ExecutionFailed {
+    status: 'failed';
+    instance_id: string;
+    failed_step_id: string;
+    failure_reason: string;
+    partial_outputs: Record<string, unknown>;
+    work_zone: string;
+}
+/** CITL 介入暂停信号（confirm 审批 / ask 数据收集）：自包含介入请求，caller 拿到即知看什么给什么。见 [[hop-cli#^anc-cli-execution-paused]] */
+export interface ExecutionPaused {
+    status: 'paused';
+    instance_id: string;
+    step_id: string;
+    pause_reason: 'confirm' | 'commit' | 'waiting_human' | 'ask';
+    presented_data: {
+        summary: string;
+        question?: string;
+        instruction: string;
+        engine_impact?: string;
+        context?: Record<string, unknown>;
+        output_schema?: OutputDecl[];
+        default_value?: unknown;
+        present_inputs?: string[];
+    };
+    response_options: ResponseOption[];
+    timeout_seconds?: number;
+    timeout_action?: 'fail' | 'default_response';
+    work_zone: string;
+}
+/** done/fail/branch/answer 命令的通用响应：ok 或带错误码的 error。见 [[hop-cli#^anc-cli-command-response]] */
+export interface CommandResponse {
+    status: 'ok' | 'error';
+    code?: ErrorCode;
+    message?: string;
+}
+/** hopjit vars 响应：实例当前变量表与尚未赋值的 Outputs 变量名。见 [[hop-cli#^anc-cli-vars-response]] */
+export interface VarsResponse {
+    status: 'ok';
+    instance_id: string;
+    execution_status: 'running' | 'completed' | 'failed';
+    variables: Record<string, unknown>;
+    pending_outputs: string[];
+}
+/** hopjit status 响应：实例执行状态与步骤计数（总/完成/失败/待执行/当前）。见 [[hop-cli#^anc-cli-status-response]] */
+export interface StatusResponse {
+    status: 'ok';
+    instance_id: string;
+    execution_status: 'running' | 'completed' | 'failed';
+    total_steps: number;
+    completed: number;
+    failed: number;
+    pending: number;
+    current_step?: string;
+}
+/** hopjit replan 响应联合：重规划成功或解析/校验失败。见 [[hop-cli#^anc-cli-replan-response]] */
+export type ReplanResponse = ReplanSuccess | ReplanError;
+/** replan 成功：返回替换后的新步骤摘要。见 [[hop-cli#^anc-cli-replan-response]] */
+export interface ReplanSuccess {
+    status: 'ok';
+    new_children: StepSummary[];
+}
+/** replan 失败：携错误码与解析或校验错误。见 [[hop-cli#^anc-cli-replan-response]] */
+export interface ReplanError {
+    status: 'error';
+    code: ErrorCode;
+    errors: SpecError[];
+}
+/** hopjit branch 请求体：手动覆盖引擎自动条件评估，用于调试或外部 HITL 介入。见 [[hop-cli#^anc-cli-branch-request]] */
+export interface BranchRequest {
+    step_id: string;
+    selected_case_id: string;
+    reason?: string;
+}

package/dist/cli-types.js

@@ -0,0 +1,4 @@
+// @module: hop-cli ^anc-struct-hop-cli
+// CLI 响应/请求类型——**包级对外稳定面**（driver 依赖的 JSON 结构，破坏即破坏 driver，包级 MAJOR）。
+// 拆自原 types.ts（见 design/spec-ast.md ^anc-struct-spec-ast 拆分表）。
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import type { HostConfig } from './provider-types.js';
+declare const program: Command;
+/** 把结果序列化为单行 JSON 写 stdout——CLI 对 Agent 消费方的结构化输出约定。见 [[hop-cli#^anc-cli-json-io]] */
+export declare function output(data: unknown): void;
+/** 运行时错误（参数非法、IO 失败）写 stderr 并以非零 exit code 退出，与业务错误的 stdout JSON 分流。见 [[hop-cli#^anc-cli-json-io]] */
+export declare function errorExit(message: string, code?: number): never;
+export declare function resolveFileArgBase(filePath: string, workZoneBase?: string): string;
+/** 解析 JSON 参数：`@file` 前缀从文件读取（走 worker work_zone 重定向），否则原样 JSON.parse。见 [[hop-cli#^anc-cli-file-arg-safety]] */
+export declare function resolveParam(value: string | undefined, workZoneBase?: string): unknown;
+/** 提交越界校验：`--output @<path>` 的解析路径必须落在本执行单元 work_zone 内，越界（/tmp、
+ * 项目根、兄弟 child）→ 抛错拒绝提交。引擎唯一能真拦的点（复用模式 act 由 CC 执行、写入不过引擎，
+ * 只能提交时校验）。回归 ppt-html v4 串台：worker 写共享 /tmp 互相覆盖。见 [[hop-cli#^anc-cli-file-arg-safety]]。
+ * @a: anc-cli-file-arg-safety */
+export declare function assertOutputInWorkZone(value: string | undefined, instanceDir: string, workZoneBase?: string): void;
+/** 解析文本参数（如 --steps/--reason）：`@file` 前缀读文件原文，否则返回原值——LLM 生成内容经 @file 防注入。见 [[hop-cli#^anc-cli-file-arg-safety]] */
+export declare function resolveTextParam(value: string | undefined, workZoneBase?: string): string | undefined;
+export declare function workerWorkZone(instanceDir: string, instanceOpt?: string): string | undefined;
+/** 解析目标实例目录：显式 --instance 直接定位，省略时取 state_dir 下最新（按 mtime）实例。见 [[hop-cli#^anc-cli-instance-resolve]] */
+export declare function resolveInstance(stateDir: string, instanceId?: string): string;
+/** 构造 CLI 默认 HostConfig（workspace=cwd + 默认沙箱），供独立模式命令实例化 Engine/Dispatcher。见 [[hop-cli#^anc-struct-hop-cli]] */
+export declare function buildHostConfig(): HostConfig;
+/** context 精简档 resolve：env HOPJIT_CONTEXT_MODE > --context-mode flag > 默认 full。见 [[prompt-assembler#^anc-exec-context-mode]] */
+export declare function resolveContextMode(flag?: string): 'full' | 'minimal';
+export { program };