@nt-ai-lab/deterministic-agent-workflow-cli 0.1.0

package/dist/features/workflow-cli/entrypoint/workflow-cli.d.ts

@@ -0,0 +1,4 @@
+import type { BaseWorkflowState, RehydratableWorkflow } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { WorkflowCliConfig } from '../../../platform/domain/workflow-cli-types';
+/** @riviere-role cli-entrypoint */
+export declare function createWorkflowCli<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState, TDeps>(config: WorkflowCliConfig<TWorkflow, TState, TDeps>): void;

package/dist/features/workflow-cli/entrypoint/workflow-cli.js

@@ -0,0 +1,81 @@
+import { join } from 'node:path';
+import { createWorkflowRunner } from '../../workflow-runner/entrypoint/workflow-runner.js';
+import { getRepositoryName } from '../../../platform/infra/external-clients/git/repository-name.js';
+function buildReadEnvVar(getEnv) {
+    return function readEnvVar(name) {
+        const value = getEnv(name);
+        if (value === undefined || value === '') {
+            throw new TypeError(`Missing required environment variable: ${name}`);
+        }
+        return value;
+    };
+}
+/** @riviere-role cli-entrypoint */
+export function createWorkflowCli(config) {
+    const { processDeps } = config;
+    const readEnvVar = buildReadEnvVar(processDeps.getEnv);
+    const pluginRoot = readEnvVar('CLAUDE_PLUGIN_ROOT');
+    const getSessionId = () => readEnvVar('CLAUDE_SESSION_ID');
+    const configuredWorkflowEventsDbPath = processDeps.getEnv('WORKFLOW_EVENTS_DB');
+    const workflowEventsDbPath = configuredWorkflowEventsDbPath !== undefined && configuredWorkflowEventsDbPath !== ''
+        ? configuredWorkflowEventsDbPath
+        : join(readEnvVar('HOME'), '.workflow-events.db');
+    const store = processDeps.buildStore(workflowEventsDbPath);
+    const now = () => new Date().toISOString();
+    const platformCtx = {
+        getPluginRoot: () => pluginRoot,
+        now,
+        getSessionId,
+        store,
+    };
+    const engineDeps = {
+        store,
+        getPluginRoot: () => pluginRoot,
+        getEnvFilePath: () => join(readEnvVar('HOME'), '.claude', 'claude.env'),
+        getRepositoryName: () => getRepositoryName(process.cwd()),
+        readFile: processDeps.readFile,
+        appendToFile: processDeps.appendToFile,
+        now,
+        transcriptReader: config.transcriptReader,
+    };
+    const workflowDeps = config.buildWorkflowDeps(platformCtx);
+    const readStdin = () => processDeps.readFile('/dev/stdin');
+    const errorLogPath = join(pluginRoot, 'error.log');
+    try {
+        const args = processDeps.getArgv().slice(2);
+        const command = args[0];
+        if (args.length > 0 && config.customRouter !== undefined) {
+            const custom = config.customRouter(command, args, platformCtx);
+            if (custom !== undefined) {
+                writeRunnerResult(processDeps, custom);
+                return;
+            }
+        }
+        const runner = createWorkflowRunner(config);
+        const result = runner(args, engineDeps, workflowDeps, {
+            readStdin,
+            getSessionId,
+        });
+        if (result.output) {
+            processDeps.writeStdout(result.output);
+        }
+        processDeps.exit(result.exitCode);
+    }
+    catch (error) {
+        const message = `[${new Date().toISOString()}] ERROR: ${String(error)}\n`;
+        processDeps.writeStderr(message);
+        try {
+            processDeps.appendToFile(errorLogPath, message);
+        }
+        catch {
+            // Ignore write failures to error log.
+        }
+        processDeps.exit(1);
+    }
+}
+function writeRunnerResult(processDeps, result) {
+    if (result.output !== '') {
+        processDeps.writeStdout(result.output);
+    }
+    processDeps.exit(result.exitCode);
+}

package/dist/features/workflow-runner/entrypoint/workflow-runner.d.ts

@@ -0,0 +1,5 @@
+import type { BaseWorkflowState, RehydratableWorkflow, WorkflowEngineDeps } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { RunnerOptions, RunnerResult, WorkflowRunnerConfig } from '../../../platform/domain/workflow-runner-types';
+export type { PreToolUseHandlerFn } from '../../../platform/domain/pre-tool-use-handler';
+/** @riviere-role cli-entrypoint */
+export declare function createWorkflowRunner<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string>(config: WorkflowRunnerConfig<TWorkflow, TState, TDeps, TStateName, TOperation>): (args: readonly string[], engineDeps: WorkflowEngineDeps, workflowDeps: TDeps, options?: RunnerOptions) => RunnerResult;

package/dist/features/workflow-runner/entrypoint/workflow-runner.js

@@ -0,0 +1,216 @@
+import { WorkflowEngine } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import { EXIT_ALLOW, EXIT_BLOCK, EXIT_ERROR } from '../../../shell/exit-codes.js';
+import { formatContextInjection, formatDenyDecision } from '../../../platform/infra/cli/presentation/hook-output.js';
+import { hookCommonInputSchema, preToolUseInputSchema, subagentStartInputSchema, teammateIdleInputSchema, } from '../../../platform/infra/external-clients/claude-hooks/hook-schemas.js';
+import { createPreToolUseHandler } from '../../../platform/domain/pre-tool-use-handler.js';
+import { getRepositoryName } from '../../../platform/infra/external-clients/git/repository-name.js';
+function resolvePreToolUseHandler(config) {
+    const hasPolicy = config.bashForbidden !== undefined || config.isWriteAllowed !== undefined || config.customGates !== undefined;
+    if (config.preToolUseHandler !== undefined) {
+        if (hasPolicy) {
+            throw new TypeError('WorkflowRunnerConfig: preToolUseHandler is mutually exclusive with bashForbidden/isWriteAllowed/customGates. Provide either policy fields (default path) or a custom handler (escape hatch), not both.');
+        }
+        return config.preToolUseHandler;
+    }
+    if (config.bashForbidden === undefined && config.isWriteAllowed === undefined) {
+        if (config.customGates !== undefined) {
+            throw new TypeError('WorkflowRunnerConfig: customGates requires bashForbidden and isWriteAllowed to also be set.');
+        }
+        return undefined;
+    }
+    if (config.bashForbidden === undefined || config.isWriteAllowed === undefined) {
+        throw new TypeError('WorkflowRunnerConfig: bashForbidden and isWriteAllowed must be provided together.');
+    }
+    if (config.customGates === undefined) {
+        return createPreToolUseHandler({
+            bashForbidden: config.bashForbidden,
+            isWriteAllowed: config.isWriteAllowed
+        });
+    }
+    return createPreToolUseHandler({
+        bashForbidden: config.bashForbidden,
+        isWriteAllowed: config.isWriteAllowed,
+        customGates: config.customGates,
+    });
+}
+function engineResultToRunnerResult(result) {
+    switch (result.type) {
+        case 'success': return {
+            output: result.output,
+            exitCode: EXIT_ALLOW
+        };
+        case 'blocked': return {
+            output: result.output,
+            exitCode: EXIT_BLOCK
+        };
+        case 'error': return {
+            output: result.output,
+            exitCode: EXIT_ERROR
+        };
+    }
+}
+function parseArgs(argParsers, args, routeName) {
+    const values = [];
+    for (const [index, parser] of (argParsers ?? []).entries()) {
+        const result = parser.parse(args, index + 1, routeName);
+        if (!result.ok)
+            return {
+                ok: false,
+                message: result.message
+            };
+        values.push(result.value);
+    }
+    return {
+        ok: true,
+        values
+    };
+}
+function assertSessionId(values) {
+    const id = values[0];
+    if (typeof id !== 'string')
+        throw new TypeError('session-id argument must be a string');
+    return id;
+}
+function assertTarget(values) {
+    const target = values[1];
+    if (typeof target !== 'string')
+        throw new TypeError('target argument must be a string');
+    return target;
+}
+/** @riviere-role cli-entrypoint */
+export function createWorkflowRunner(config) {
+    const resolvedHandler = resolvePreToolUseHandler(config);
+    return (args, engineDeps, workflowDeps, options) => {
+        const engine = new WorkflowEngine(config.workflowDefinition, engineDeps, workflowDeps);
+        if (args.length > 0) {
+            return handleRoute(engine, config, args, args[0], options?.getSessionId, options?.getSessionTranscriptPath, options?.getSessionRepository);
+        }
+        if (options?.readStdin === undefined)
+            return {
+                output: 'No command and no stdin available',
+                exitCode: EXIT_ERROR
+            };
+        return handleHook(engine, resolvedHandler, options.readStdin);
+    };
+}
+function handleRoute(engine, config, args, routeName, getSessionId, getSessionTranscriptPath, getSessionRepository) {
+    const routeDef = Object.hasOwn(config.routes, routeName) ? config.routes[routeName] : undefined;
+    if (routeDef === undefined)
+        return {
+            output: `Unknown command: ${routeName}`,
+            exitCode: EXIT_ERROR
+        };
+    const parsedArgs = parseArgs(routeDef.args, args, routeName);
+    if (!parsedArgs.ok)
+        return {
+            output: parsedArgs.message,
+            exitCode: EXIT_ERROR
+        };
+    const resolveSessionId = () => getSessionId === undefined ? assertSessionId(parsedArgs.values) : getSessionId();
+    const argsAfterSessionId = () => getSessionId === undefined ? parsedArgs.values.slice(1) : parsedArgs.values;
+    const resolveTarget = () => {
+        if (getSessionId === undefined)
+            return assertTarget(parsedArgs.values);
+        const target = parsedArgs.values[0];
+        if (typeof target !== 'string')
+            throw new TypeError('target argument must be a string');
+        return target;
+    };
+    switch (routeDef.type) {
+        case 'session-start': {
+            const transcriptPath = getSessionTranscriptPath === undefined ? '' : getSessionTranscriptPath();
+            return engineResultToRunnerResult(engine.startSession(resolveSessionId(), transcriptPath, getSessionRepository?.()));
+        }
+        case 'transition':
+            return engineResultToRunnerResult(engine.transition(resolveSessionId(), config.workflowDefinition.stateSchema.parse(resolveTarget())));
+        case 'transaction':
+            return engineResultToRunnerResult(engine.transaction(resolveSessionId(), routeName, (workflow) => routeDef.handler(workflow, ...argsAfterSessionId())));
+    }
+}
+function handleHook(engine, resolvedHandler, readStdin) {
+    const stdin = readStdin();
+    const hookInput = JSON.parse(stdin);
+    const commonParse = hookCommonInputSchema.safeParse(hookInput);
+    if (!commonParse.success)
+        return {
+            output: `Invalid hook input: ${commonParse.error.message}`,
+            exitCode: EXIT_ERROR
+        };
+    const common = commonParse.data;
+    if (common.hook_event_name === 'SessionStart') {
+        const result = engine.startSession(common.session_id, common.transcript_path, getRepositoryName(common.cwd));
+        engine.persistSessionId(common.session_id);
+        return engineResultToRunnerResult(result);
+    }
+    if (!engine.hasSession(common.session_id))
+        return {
+            output: '',
+            exitCode: EXIT_ALLOW
+        };
+    switch (common.hook_event_name) {
+        case 'PreToolUse': return handlePreToolUseHook(engine, resolvedHandler, stdin);
+        case 'SubagentStart': return handleSubagentStartHook(engine, stdin);
+        case 'TeammateIdle': return handleTeammateIdleHook(engine, stdin);
+        default: return {
+            output: '',
+            exitCode: EXIT_ALLOW
+        };
+    }
+}
+function handlePreToolUseHook(engine, resolvedHandler, stdin) {
+    const hookInput = JSON.parse(stdin);
+    const toolParse = preToolUseInputSchema.safeParse(hookInput);
+    if (!toolParse.success)
+        return {
+            output: `Invalid pre-tool-use input: ${toolParse.error.message}`,
+            exitCode: EXIT_ERROR
+        };
+    return handlePreToolUse(engine, resolvedHandler, toolParse.data);
+}
+function handlePreToolUse(engine, resolvedHandler, input) {
+    if (resolvedHandler === undefined)
+        return {
+            output: '',
+            exitCode: EXIT_ALLOW
+        };
+    const result = resolvedHandler(engine, input.session_id, input.tool_name, input.tool_input);
+    if (result.type === 'blocked')
+        return {
+            output: formatDenyDecision(result.output),
+            exitCode: EXIT_BLOCK
+        };
+    return engineResultToRunnerResult(result);
+}
+function handleSubagentStartHook(engine, stdin) {
+    const hookInput = JSON.parse(stdin);
+    const parsed = subagentStartInputSchema.safeParse(hookInput);
+    if (!parsed.success)
+        return {
+            output: `Invalid subagent-start input: ${parsed.error.message}`,
+            exitCode: EXIT_ERROR
+        };
+    const input = parsed.data;
+    const result = engine.transaction(input.session_id, 'register-agent', (workflow) => workflow.registerAgent(input.agent_type, input.agent_id));
+    return {
+        output: formatContextInjection(result.type === 'success' ? result.output : ''),
+        exitCode: EXIT_ALLOW
+    };
+}
+function handleTeammateIdleHook(engine, stdin) {
+    const hookInput = JSON.parse(stdin);
+    const parsed = teammateIdleInputSchema.safeParse(hookInput);
+    if (!parsed.success)
+        return {
+            output: `Invalid teammate-idle input: ${parsed.error.message}`,
+            exitCode: EXIT_ERROR
+        };
+    const input = parsed.data;
+    const agentName = resolveTeammateName(input.teammate_name);
+    return engineResultToRunnerResult(engine.transaction(input.session_id, 'check-idle', (workflow) => workflow.handleTeammateIdle(agentName)));
+}
+function resolveTeammateName(teammateName) {
+    if (teammateName === undefined) {
+        return '';
+    }
+    return teammateName;
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { arg } from './platform/infra/cli/input/argument-parser';
+export type { ArgParser, ArgResult, } from './platform/domain/argument-parser-types';
+export { extractField } from './platform/domain/extract-field';
+export { defineRoutes } from './platform/domain/command-definition';
+export type { RouteDefinition, RouteMap, } from './platform/domain/command-definition';
+export { createWorkflowRunner } from './features/workflow-runner/entrypoint/workflow-runner';
+export type { RunnerResult, RunnerOptions, WorkflowRunnerConfig, } from './platform/domain/workflow-runner-types';
+export type { PreToolUseHandlerFn } from './platform/domain/pre-tool-use-handler';
+export { createPreToolUseHandler } from './platform/domain/pre-tool-use-handler';
+export type { PreToolUseHandlerConfig, CustomPreToolUseGate, } from './platform/domain/pre-tool-use-handler';
+export { formatContextInjection, formatDenyDecision, } from './platform/infra/cli/presentation/hook-output';
+export { createWorkflowCli } from './features/workflow-cli/entrypoint/workflow-cli';
+export type { ProcessDeps, WorkflowCliConfig, } from './platform/domain/workflow-cli-types';
+export { createDefaultProcessDeps } from './platform/infra/external-clients/process/default-process-deps';
+export type { PlatformContext } from './platform/domain/platform-context';
+export { getRepositoryName } from './platform/infra/external-clients/git/repository-name';
+export { EXIT_ALLOW, EXIT_BLOCK, EXIT_ERROR, } from './shell/exit-codes';
+export { hookCommonInputSchema, preToolUseInputSchema, subagentStartInputSchema, teammateIdleInputSchema, } from './platform/infra/external-clients/claude-hooks/hook-schemas';
+export type { PreToolUseInput, SubagentStartInput, TeammateIdleInput, } from './platform/infra/external-clients/claude-hooks/hook-schemas';

package/dist/index.js

@@ -0,0 +1,11 @@
+export { arg } from './platform/infra/cli/input/argument-parser.js';
+export { extractField } from './platform/domain/extract-field.js';
+export { defineRoutes } from './platform/domain/command-definition.js';
+export { createWorkflowRunner } from './features/workflow-runner/entrypoint/workflow-runner.js';
+export { createPreToolUseHandler } from './platform/domain/pre-tool-use-handler.js';
+export { formatContextInjection, formatDenyDecision, } from './platform/infra/cli/presentation/hook-output.js';
+export { createWorkflowCli } from './features/workflow-cli/entrypoint/workflow-cli.js';
+export { createDefaultProcessDeps } from './platform/infra/external-clients/process/default-process-deps.js';
+export { getRepositoryName } from './platform/infra/external-clients/git/repository-name.js';
+export { EXIT_ALLOW, EXIT_BLOCK, EXIT_ERROR, } from './shell/exit-codes.js';
+export { hookCommonInputSchema, preToolUseInputSchema, subagentStartInputSchema, teammateIdleInputSchema, } from './platform/infra/external-clients/claude-hooks/hook-schemas.js';

package/dist/platform/domain/argument-parser-types.d.ts

@@ -0,0 +1,13 @@
+/** @riviere-role value-object */
+export type ArgResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** @riviere-role value-object */
+export type ArgParser<T> = {
+    readonly parse: (args: readonly string[], position: number, commandName: string) => ArgResult<T>;
+    readonly optional: () => ArgParser<T | undefined>;
+};

package/dist/platform/domain/argument-parser-types.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/domain/command-definition.d.ts

@@ -0,0 +1,26 @@
+import type { PreconditionResult } from '@nt-ai-lab/deterministic-agent-workflow-dsl';
+import type { ArgParser } from './argument-parser-types';
+type RouteHandler<TWorkflow> = (workflow: TWorkflow, ...parsedArgs: readonly unknown[]) => PreconditionResult;
+type TransactionRoute<TWorkflow> = {
+    readonly type: 'transaction';
+    readonly args?: readonly ArgParser<unknown>[];
+    readonly handler: RouteHandler<TWorkflow>;
+};
+type TransitionRoute = {
+    readonly type: 'transition';
+    readonly args?: readonly ArgParser<unknown>[];
+};
+type SessionStartRoute = {
+    readonly type: 'session-start';
+    readonly args?: readonly ArgParser<unknown>[];
+};
+type RouteStateMarker<TState> = {
+    readonly __stateBrand?: TState;
+};
+/** @riviere-role value-object */
+export type RouteDefinition<TWorkflow, TState> = (TransactionRoute<TWorkflow> | TransitionRoute | SessionStartRoute) & RouteStateMarker<TState>;
+/** @riviere-role value-object */
+export type RouteMap<TWorkflow, TState> = Record<string, RouteDefinition<TWorkflow, TState>>;
+/** @riviere-role domain-service */
+export declare function defineRoutes<TWorkflow, TState>(routes: RouteMap<TWorkflow, TState>): RouteMap<TWorkflow, TState>;
+export {};

package/dist/platform/domain/command-definition.js

@@ -0,0 +1,4 @@
+/** @riviere-role domain-service */
+export function defineRoutes(routes) {
+    return routes;
+}

package/dist/platform/domain/extract-field.d.ts

@@ -0,0 +1,2 @@
+/** @riviere-role domain-service */
+export declare function extractField(fieldName: string): (toolInput: Record<string, unknown>) => string;

package/dist/platform/domain/extract-field.js

@@ -0,0 +1,13 @@
+/** @riviere-role domain-service */
+export function extractField(fieldName) {
+    return (toolInput) => {
+        const value = toolInput[fieldName];
+        if (value === undefined || value === null) {
+            return '';
+        }
+        if (typeof value !== 'string') {
+            throw new TypeError(`Expected '${fieldName}' to be a string, got ${typeof value}`);
+        }
+        return value;
+    };
+}

package/dist/platform/domain/platform-context.d.ts

@@ -0,0 +1,8 @@
+import type { WorkflowEventStore } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+/** @riviere-role value-object */
+export type PlatformContext = {
+    readonly getPluginRoot: () => string;
+    readonly now: () => string;
+    readonly getSessionId: () => string;
+    readonly store: WorkflowEventStore;
+};

package/dist/platform/domain/platform-context.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/domain/pre-tool-use-handler.d.ts

@@ -0,0 +1,21 @@
+import type { BaseWorkflowState, EngineResult, RehydratableWorkflow, WorkflowEngine } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { BashForbiddenConfig } from '@nt-ai-lab/deterministic-agent-workflow-dsl';
+/** @riviere-role value-object */
+export type PreToolUseHandlerFn<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string> = (engine: WorkflowEngine<TWorkflow, TState, TDeps, TStateName, TOperation>, sessionId: string, toolName: string, toolInput: Record<string, unknown>) => EngineResult;
+/** @riviere-role value-object */
+export type CustomPreToolUseGate<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TStateName extends string = string> = {
+    readonly name: string;
+    readonly check: (workflow: TWorkflow, ctx: {
+        readonly toolName: string;
+        readonly filePath: string;
+        readonly command: string;
+    }) => true | string;
+};
+/** @riviere-role value-object */
+export type PreToolUseHandlerConfig<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TStateName extends string = string> = {
+    readonly bashForbidden: BashForbiddenConfig;
+    readonly isWriteAllowed: (filePath: string, state: TState) => boolean;
+    readonly customGates?: readonly CustomPreToolUseGate<TWorkflow, TState, TStateName>[];
+};
+/** @riviere-role domain-service */
+export declare function createPreToolUseHandler<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string>(config: PreToolUseHandlerConfig<TWorkflow, TState, TStateName>): PreToolUseHandlerFn<TWorkflow, TState, TDeps, TStateName, TOperation>;

package/dist/platform/domain/pre-tool-use-handler.js

@@ -0,0 +1,44 @@
+/** @riviere-role domain-service */
+export function createPreToolUseHandler(config) {
+    return (engine, sessionId, toolName, toolInput) => {
+        const filePath = extractFilePath(toolInput);
+        const command = extractCommand(toolInput);
+        const ctx = {
+            toolName,
+            filePath,
+            command
+        };
+        for (const gate of config.customGates ?? []) {
+            const result = engine.transaction(sessionId, `hook:${gate.name}`, (workflow) => {
+                const check = gate.check(workflow, ctx);
+                if (check === true)
+                    return { pass: true };
+                return {
+                    pass: false,
+                    reason: check
+                };
+            });
+            if (result.type === 'blocked')
+                return result;
+        }
+        const writeCheck = engine.checkWrite(sessionId, toolName, filePath, config.isWriteAllowed);
+        if (writeCheck.type === 'blocked')
+            return writeCheck;
+        return engine.checkBash(sessionId, toolName, command, config.bashForbidden);
+    };
+}
+function extractFilePath(toolInput) {
+    return resolveStringField(toolInput['file_path'])
+        || resolveStringField(toolInput['path'])
+        || resolveStringField(toolInput['pattern']);
+}
+function extractCommand(toolInput) {
+    return resolveStringField(toolInput['command']);
+}
+function resolveStringField(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    throw new TypeError(`Expected string or undefined in tool_input field. Got ${typeof value}: ${String(value)}`);
+}

package/dist/platform/domain/workflow-cli-types.d.ts

@@ -0,0 +1,21 @@
+import type { BaseWorkflowState, RehydratableWorkflow, TranscriptReader, WorkflowEventStore } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { PlatformContext } from './platform-context';
+import type { RunnerResult, WorkflowRunnerConfig } from './workflow-runner-types';
+/** @riviere-role value-object */
+export type ProcessDeps = {
+    readonly getEnv: (name: string) => string | undefined;
+    readonly exit: (code: number) => void;
+    readonly writeStdout: (s: string) => void;
+    readonly writeStderr: (s: string) => void;
+    readonly getArgv: () => readonly string[];
+    readonly readFile: (path: string) => string;
+    readonly appendToFile: (path: string, content: string) => void;
+    readonly buildStore: (dbPath: string) => WorkflowEventStore;
+};
+/** @riviere-role value-object */
+export type WorkflowCliConfig<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState, TDeps> = WorkflowRunnerConfig<TWorkflow, TState, TDeps> & {
+    readonly buildWorkflowDeps: (platform: PlatformContext) => TDeps;
+    readonly customRouter?: (command: string, args: readonly string[], platform: PlatformContext) => RunnerResult | undefined;
+    readonly processDeps: ProcessDeps;
+    readonly transcriptReader: TranscriptReader;
+};

package/dist/platform/domain/workflow-cli-types.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/domain/workflow-runner-types.d.ts

@@ -0,0 +1,25 @@
+import type { BaseWorkflowState, RehydratableWorkflow, WorkflowDefinition } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { BashForbiddenConfig } from '@nt-ai-lab/deterministic-agent-workflow-dsl';
+import type { RouteMap } from './command-definition';
+import type { CustomPreToolUseGate, PreToolUseHandlerFn } from './pre-tool-use-handler';
+/** @riviere-role value-object */
+export type RunnerResult = {
+    readonly output: string;
+    readonly exitCode: number;
+};
+/** @riviere-role value-object */
+export type RunnerOptions = {
+    readonly readStdin?: () => string;
+    readonly getSessionId?: () => string;
+    readonly getSessionTranscriptPath?: () => string;
+    readonly getSessionRepository?: () => string | undefined;
+};
+/** @riviere-role value-object */
+export type WorkflowRunnerConfig<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string> = {
+    readonly workflowDefinition: WorkflowDefinition<TWorkflow, TState, TDeps, TStateName, TOperation>;
+    readonly routes: RouteMap<TWorkflow, TState>;
+    readonly bashForbidden?: BashForbiddenConfig;
+    readonly isWriteAllowed?: (filePath: string, state: TState) => boolean;
+    readonly customGates?: readonly CustomPreToolUseGate<TWorkflow, TState, TStateName>[];
+    readonly preToolUseHandler?: PreToolUseHandlerFn<TWorkflow, TState, TDeps, TStateName, TOperation>;
+};

package/dist/platform/domain/workflow-runner-types.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/infra/cli/input/argument-parser.d.ts

@@ -0,0 +1,9 @@
+import type { ZodType } from 'zod';
+import type { ArgParser } from '../../../domain/argument-parser-types';
+/** @riviere-role cli-input-validator */
+export declare const arg: {
+    number: (name: string) => ArgParser<number>;
+    string: (name: string) => ArgParser<string>;
+    rest: () => ArgParser<readonly string[]>;
+    state: <T extends string>(name: string, schema: ZodType<T>) => ArgParser<T>;
+};

package/dist/platform/infra/cli/input/argument-parser.js

@@ -0,0 +1,93 @@
+function makeOptional(parser) {
+    return {
+        parse: (args, position, commandName) => {
+            if (position >= args.length) {
+                return {
+                    ok: true,
+                    value: undefined
+                };
+            }
+            return parser.parse(args, position, commandName);
+        },
+        optional: () => makeOptional(parser),
+    };
+}
+/** @riviere-role cli-input-validator */
+export const arg = {
+    number: (name) => ({
+        parse: (args, position, commandName) => {
+            if (position >= args.length) {
+                return {
+                    ok: false,
+                    message: `${commandName}: missing required argument <${name}>`
+                };
+            }
+            const raw = args[position];
+            const parsed = Number.parseInt(raw, 10);
+            if (Number.isNaN(parsed)) {
+                return {
+                    ok: false,
+                    message: `${commandName}: not a valid number: '${raw}'`
+                };
+            }
+            return {
+                ok: true,
+                value: parsed
+            };
+        },
+        optional: function () {
+            return makeOptional(this);
+        },
+    }),
+    string: (name) => ({
+        parse: (args, position, commandName) => {
+            if (position >= args.length) {
+                return {
+                    ok: false,
+                    message: `${commandName}: missing required argument <${name}>`
+                };
+            }
+            return {
+                ok: true,
+                value: args[position]
+            };
+        },
+        optional: function () {
+            return makeOptional(this);
+        },
+    }),
+    rest: () => ({
+        parse: (args, position) => ({
+            ok: true,
+            value: args.slice(position)
+        }),
+        optional: function () {
+            return makeOptional(this);
+        },
+    }),
+    state: (name, schema) => ({
+        parse: (args, position, commandName) => {
+            if (position >= args.length) {
+                return {
+                    ok: false,
+                    message: `${commandName}: missing required argument <${name}>`
+                };
+            }
+            const raw = args[position];
+            const result = schema.safeParse(raw);
+            if (!result.success) {
+                return {
+                    ok: false,
+                    message: `${commandName}: invalid state '${raw}'`
+                };
+            }
+            return {
+                ok: true,
+                value: result.data
+            };
+        },
+        optional: function () {
+            return makeOptional(this);
+        },
+    }),
+};

package/dist/platform/infra/cli/presentation/hook-output.d.ts

@@ -0,0 +1,4 @@
+/** @riviere-role cli-output-formatter */
+export declare function formatDenyDecision(reason: string): string;
+/** @riviere-role cli-output-formatter */
+export declare function formatContextInjection(context: string): string;

package/dist/platform/infra/cli/presentation/hook-output.js

@@ -0,0 +1,14 @@
+/** @riviere-role cli-output-formatter */
+export function formatDenyDecision(reason) {
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: reason,
+        },
+    });
+}
+/** @riviere-role cli-output-formatter */
+export function formatContextInjection(context) {
+    return JSON.stringify({ additionalContext: context });
+}

package/dist/platform/infra/external-clients/claude-hooks/hook-schemas.d.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+declare const hookCommonInputSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    hook_event_name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: string;
+    permission_mode?: string | undefined;
+}, {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: string;
+    permission_mode?: string | undefined;
+}>;
+declare const preToolUseInputSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    hook_event_name: z.ZodString;
+} & {
+    tool_name: z.ZodString;
+    tool_input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    tool_use_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: string;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    tool_use_id: string;
+    permission_mode?: string | undefined;
+}, {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: string;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    tool_use_id: string;
+    permission_mode?: string | undefined;
+}>;
+declare const subagentStartInputSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    hook_event_name: z.ZodString;
+} & {
+    agent_id: z.ZodString;
+    agent_type: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: string;
+    agent_id: string;
+    agent_type: string;
+    permission_mode?: string | undefined;
+}, {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: string;
+    agent_id: string;
+    agent_type: string;
+    permission_mode?: string | undefined;
+}>;
+declare const teammateIdleInputSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    hook_event_name: z.ZodString;
+} & {
+    teammate_name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: string;
+    permission_mode?: string | undefined;
+    teammate_name?: string | undefined;
+}, {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: string;
+    permission_mode?: string | undefined;
+    teammate_name?: string | undefined;
+}>;
+/** @riviere-role external-client-model */
+export type PreToolUseInput = z.infer<typeof preToolUseInputSchema>;
+/** @riviere-role external-client-model */
+export type SubagentStartInput = z.infer<typeof subagentStartInputSchema>;
+/** @riviere-role external-client-model */
+export type TeammateIdleInput = z.infer<typeof teammateIdleInputSchema>;
+export { hookCommonInputSchema, preToolUseInputSchema, subagentStartInputSchema, teammateIdleInputSchema, };

package/dist/platform/infra/external-clients/claude-hooks/hook-schemas.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+const hookCommonInputSchema = z.object({
+    session_id: z.string(),
+    transcript_path: z.string(),
+    cwd: z.string(),
+    permission_mode: z.string().optional(),
+    hook_event_name: z.string(),
+});
+const preToolUseInputSchema = hookCommonInputSchema.extend({
+    tool_name: z.string(),
+    tool_input: z.record(z.unknown()),
+    tool_use_id: z.string(),
+});
+const subagentStartInputSchema = hookCommonInputSchema.extend({
+    agent_id: z.string(),
+    agent_type: z.string(),
+});
+const teammateIdleInputSchema = hookCommonInputSchema.extend({ teammate_name: z.string().optional(), });
+export { hookCommonInputSchema, preToolUseInputSchema, subagentStartInputSchema, teammateIdleInputSchema, };

package/dist/platform/infra/external-clients/git/repository-name.d.ts

@@ -0,0 +1,2 @@
+/** @riviere-role external-client-service */
+export declare function getRepositoryName(cwd: string): string | undefined;

package/dist/platform/infra/external-clients/git/repository-name.js

@@ -0,0 +1,22 @@
+import { execFileSync } from 'node:child_process';
+const httpsRemotePattern = /github\.com\/([^/]+\/[^/.]+?)(?:\.git)?$/;
+const sshRemotePattern = /github\.com:([^/]+\/[^/.]+?)(?:\.git)?$/;
+/** @riviere-role external-client-service */
+export function getRepositoryName(cwd) {
+    try {
+        const url = execFileSync('/usr/bin/git', ['remote', 'get-url', 'origin'], {
+            encoding: 'utf-8',
+            cwd,
+        }).trim();
+        const httpsMatch = httpsRemotePattern.exec(url);
+        if (httpsMatch?.[1] !== undefined)
+            return httpsMatch[1];
+        const sshMatch = sshRemotePattern.exec(url);
+        if (sshMatch?.[1] !== undefined)
+            return sshMatch[1];
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/platform/infra/external-clients/process/default-process-deps.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessDeps } from '../../../domain/workflow-cli-types';
+/** @riviere-role external-client-service */
+export declare function createDefaultProcessDeps(): ProcessDeps;

package/dist/platform/infra/external-clients/process/default-process-deps.js

@@ -0,0 +1,15 @@
+import { appendFileSync, readFileSync } from 'node:fs';
+import { createStore } from '@nt-ai-lab/deterministic-agent-workflow-event-store';
+/** @riviere-role external-client-service */
+export function createDefaultProcessDeps() {
+    return {
+        getEnv: (name) => process.env[name],
+        exit: (code) => process.exit(code),
+        writeStdout: (value) => { process.stdout.write(value); },
+        writeStderr: (value) => { process.stderr.write(value); },
+        getArgv: () => process.argv,
+        readFile: (path) => readFileSync(path, 'utf8'),
+        appendToFile: (path, content) => appendFileSync(path, content),
+        buildStore: (dbPath) => createStore(dbPath),
+    };
+}

package/dist/shell/exit-codes.d.ts

@@ -0,0 +1,3 @@
+export declare const EXIT_ALLOW = 0;
+export declare const EXIT_ERROR = 1;
+export declare const EXIT_BLOCK = 2;

package/dist/shell/exit-codes.js

@@ -0,0 +1,3 @@
+export const EXIT_ALLOW = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_BLOCK = 2;

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@nt-ai-lab/deterministic-agent-workflow-cli",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@nt-ai-lab/deterministic-agent-workflow-engine": "workspace:*",
+    "@nt-ai-lab/deterministic-agent-workflow-dsl": "workspace:*",
+    "@nt-ai-lab/deterministic-agent-workflow-event-store": "workspace:*",
+    "zod": "^3.25.76"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}