apcore-cli 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,5 +1,146 @@
 import { Command } from 'commander';
 
+/**
+ * Determines which modules are exposed as CLI commands.
+ *
+ * Filtering modes:
+ * - `all`: every discovered module becomes a CLI command (default).
+ * - `include`: only modules matching at least one include pattern are exposed.
+ * - `exclude`: all modules are exposed except those matching any exclude pattern.
+ */
+declare class ExposureFilter {
+    static readonly VALID_MODES: readonly ["all", "include", "exclude", "none"];
+    readonly _mode: string;
+    private readonly _compiledInclude;
+    private readonly _compiledExclude;
+    constructor(mode?: string, include?: string[], exclude?: string[]);
+    /** Return true if the module should be exposed as a CLI command. */
+    isExposed(moduleId: string): boolean;
+    /** Partition moduleIds into [exposed, hidden] lists. */
+    filterModules(moduleIds: string[]): [string[], string[]];
+    /**
+     * Create an ExposureFilter from a parsed config dict.
+     *
+     * Expected: `{ expose: { mode: "include", include: ["admin.*"] } }`
+     */
+    static fromConfig(config: Record<string, unknown>): ExposureFilter;
+}
+
+/**
+ * Built-in Command Group (FE-13).
+ *
+ * Encapsulates visibility resolution and subcommand filtering for the
+ * reserved `apcli` group. Instantiated once by createCli() and attached
+ * to the root command.
+ *
+ * Shape mirrors `src/exposure.ts` ExposureFilter: private constructor,
+ * named static factories, and a small set of predicate methods.
+ * See the feature spec §4.2–4.7 for authoritative semantics.
+ */
+/**
+ * Resolved visibility mode.
+ *
+ * `"auto"` is an internal sentinel — it is never returned from
+ * {@link ApcliGroup.resolveVisibility} and is rejected when supplied via
+ * user config (CliConfig or apcore.yaml).
+ */
+type ApcliMode = "auto" | "all" | "none" | "include" | "exclude";
+/**
+ * User-facing apcli config shape.
+ *
+ * Boolean shorthand maps to `{mode: "all"}` / `{mode: "none"}`.
+ * Object form rejects `"auto"` per spec §4.2 (internal sentinel only).
+ */
+type ApcliConfig = boolean | {
+    mode?: Exclude<ApcliMode, "auto">;
+    include?: string[];
+    exclude?: string[];
+    disableEnv?: boolean;
+};
+/** Set of group names reserved by apcore-cli (checked in cli.ts). */
+declare const RESERVED_GROUP_NAMES: ReadonlySet<string>;
+/**
+ * Visibility configuration for the built-in `apcli` command group.
+ *
+ * Instantiated via {@link ApcliGroup.fromCliConfig} (Tier 1) or
+ * {@link ApcliGroup.fromYaml} (Tier 3). The constructor is private to
+ * preserve the Tier-1-vs-Tier-3 flag distinction.
+ */
+declare class ApcliGroup {
+    private readonly _mode;
+    private readonly _include;
+    private readonly _exclude;
+    private readonly _disableEnv;
+    private readonly _registryInjected;
+    private readonly _fromCliConfig;
+    private constructor();
+    /**
+     * Tier 1 constructor — config came from `createCli({ apcli })`.
+     *
+     * A non-auto mode from this tier wins over env var and yaml.
+     */
+    static fromCliConfig(config: ApcliConfig | undefined, opts: {
+        registryInjected: boolean;
+    }): ApcliGroup;
+    /**
+     * Tier 3 constructor — config came from `apcore.yaml`.
+     *
+     * Env var (Tier 2) may override the yaml-supplied mode.
+     */
+    static fromYaml(config: unknown, opts: {
+        registryInjected: boolean;
+    }): ApcliGroup;
+    /**
+     * Non-panicking Tier 3 factory (A-001 parity with Rust's `try_from_yaml`).
+     * Returns `[instance, null]` on success or `[null, errorMessage]` on invalid input.
+     * Use this in programmatic contexts where throwing/exiting is unwanted.
+     */
+    static tryFromYaml(config: unknown, opts: {
+        registryInjected: boolean;
+    }): [ApcliGroup, null] | [null, string];
+    private static _build;
+    /**
+     * Normalize an include/exclude list. Non-array → warn and return [].
+     *
+     * Unknown but well-formed entries emit a WARNING (spec §7 error table,
+     * T-APCLI-25) but are retained in the returned list for forward-compat —
+     * if apcore-cli later adds a subcommand named `foo`, existing configs
+     * continue to work without a config change. At runtime, unknown names
+     * simply never match any registered subcommand.
+     */
+    private static _normalizeList;
+    /**
+     * Resolve effective visibility mode after applying tier precedence.
+     *
+     * Returns one of `"all" | "none" | "include" | "exclude"` — never `"auto"`.
+     *
+     * Tier order (spec §4.4):
+     *   1. CliConfig non-auto wins outright.
+     *   2. `APCORE_CLI_APCLI` env var (unless sealed by disableEnv).
+     *   3. yaml non-auto.
+     *   4. Auto-detect from registryInjected.
+     */
+    resolveVisibility(): "all" | "none" | "include" | "exclude";
+    /**
+     * True iff `subcommand` passes the include/exclude filter.
+     *
+     * Callers MUST first check {@link resolveVisibility} — this method throws
+     * under modes `"all"` or `"none"` (caller bug per spec §4.6).
+     */
+    isSubcommandIncluded(subcommand: string): boolean;
+    /** True iff the `apcli` group itself should appear in root `--help`. */
+    isGroupVisible(): boolean;
+    /**
+     * Parse APCORE_CLI_APCLI. Case-insensitive.
+     *
+     * - `show` / `1` / `true` → `"all"`
+     * - `hide` / `0` / `false` → `"none"`
+     * - Empty / unset → `null`
+     * - Anything else → warn and return `null`
+     */
+    private _parseEnv;
+}
+
 /**
  * LazyModuleGroup — Dynamic command loading from Registry.
  *
@@ -14,9 +155,72 @@ interface Registry {
     listModules(): ModuleDescriptor[];
     getModule(moduleId: string): ModuleDescriptor | null;
 }
-/** Placeholder for apcore-js Executor. */
+/** Strategy info returned by Executor.describePipeline(). */
+interface StrategyInfo {
+    name: string;
+    stepCount: number;
+    stepNames: string[];
+    description: string;
+}
+/** A step in the executor strategy (shape parity with apcore-js Step). */
+interface StrategyStep {
+    name: string;
+    pure?: boolean;
+    removable: boolean;
+    timeoutMs?: number;
+}
+/** Placeholder for apcore-js Executor. Shape-compatible with apcore-js >= 0.19.0. */
 interface Executor {
     execute(moduleId: string, input: Record<string, unknown>): Promise<unknown>;
+    /** Validate inputs without executing. Returns a PreflightResult. */
+    validate?(moduleId: string, input: Record<string, unknown>): Promise<PreflightResult>;
+    /** Execute with pipeline trace. Returns [result, PipelineTrace]. */
+    callWithTrace?(moduleId: string, input: Record<string, unknown>, options?: {
+        strategy?: string;
+    }): Promise<[unknown, PipelineTrace]>;
+    /** Stream execution — async iterator of chunks. */
+    stream?(moduleId: string, input: Record<string, unknown>): AsyncIterable<unknown>;
+    /** Call a module (synchronous-style, used by system commands). */
+    call?(moduleId: string, input: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Describe the executor's currently-set strategy. Returns StrategyInfo
+     * (apcore-js >= 0.18.0). Takes no arguments — to introspect a different
+     * strategy, use `Executor.listStrategies()` (static) via `executor.constructor`.
+     */
+    describePipeline?(): StrategyInfo;
+    /** The current execution strategy object, exposing step metadata. */
+    currentStrategy?: {
+        readonly steps: readonly StrategyStep[];
+    };
+}
+/** Result of a preflight validation check. */
+interface PreflightCheck {
+    readonly check: string;
+    readonly passed: boolean;
+    readonly error?: unknown;
+    readonly warnings?: string[];
+}
+/** Result of executor.validate() — parity with apcore-js PreflightResult. */
+interface PreflightResult {
+    readonly valid: boolean;
+    readonly requiresApproval: boolean;
+    readonly checks: readonly PreflightCheck[];
+    readonly errors?: ReadonlyArray<Record<string, unknown>>;
+}
+/** A single step in a pipeline trace — parity with apcore-js StepTrace. */
+interface PipelineTraceStep {
+    readonly name: string;
+    readonly durationMs: number;
+    readonly skipped: boolean;
+    readonly skipReason?: string | null;
+}
+/** Pipeline execution trace returned by callWithTrace() — parity with apcore-js PipelineTrace. */
+interface PipelineTrace {
+    readonly moduleId?: string;
+    readonly strategyName: string;
+    readonly totalDurationMs: number;
+    readonly success: boolean;
+    readonly steps: readonly PipelineTraceStep[];
 }
 /** Placeholder for apcore-js ModuleDescriptor. */
 interface ModuleDescriptor {
@@ -30,8 +234,6 @@ interface ModuleDescriptor {
     annotations?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
 }
-/** Built-in command names that cannot be overridden by modules. */
-declare const BUILTIN_COMMANDS: string[];
 /**
  * Dynamically loads apcore modules as Commander subcommands from Registry.
  */
@@ -87,16 +289,39 @@ declare class GroupedModuleGroup extends LazyModuleGroup {
     /** Cached LazyGroup instances */
     private groupCache;
     private groupMapBuilt;
+    /** Exposure filter (FE-12) — controls which modules appear as CLI commands */
+    exposureFilter: ExposureFilter;
+    /** Effective group depth (CLAUDE.md v0.6.0): constructor arg > APCORE_CLI_GROUP_DEPTH env > 1. */
+    readonly groupDepth: number;
+    constructor(registry: Registry, executor: Executor, helpTextMaxLength?: number, exposureFilter?: ExposureFilter, groupDepth?: number);
+    /**
+     * Resolve group depth from constructor arg > APCORE_CLI_GROUP_DEPTH env > default 1.
+     * Invalid env values (non-integer, non-positive) fall through to the default.
+     */
+    static resolveGroupDepth(explicit: number | undefined): number;
     /**
      * Determine (groupName | null, commandName) for a module from its display overlay.
+     *
+     * @param groupDepth  Number of dotted segments to consume as the group prefix.
+     *                    Defaults to 1 (e.g., "math.add" → group="math", cmd="add").
+     *                    Set to 2 for multi-level grouping (e.g., "math.trig.sin" →
+     *                    group="math.trig", cmd="sin").
      */
-    static resolveGroup(moduleId: string, descriptor: ModuleDescriptor): [string | null, string];
+    static resolveGroup(moduleId: string, descriptor: ModuleDescriptor, groupDepth?: number): [string | null, string];
     /**
      * Build the group map from registry modules.
+     *
+     * FE-13: hard-fails with exit 2 when a module resolves to the reserved
+     * `apcli` namespace in any of three ways — explicit `display.cli.group`,
+     * auto-grouped dotted prefix, or top-level alias/id. See spec §4.10.
      */
     buildGroupMap(): void;
     /**
-     * List all available command names: builtins + group names + top-level module names.
+     * List all available command names: group names + top-level module names.
+     *
+     * FE-13: the built-in subcommand list is no longer folded in here — those
+     * commands live under the `apcli` prefix and are registered directly by
+     * `createCli`.
      */
     listCommands(): string[];
     /**
@@ -111,18 +336,8 @@ declare class GroupedModuleGroup extends LazyModuleGroup {
     isGroupMapBuilt(): boolean;
 }
 
-/**
- * CLI entry point — createCli / main equivalents.
- *
- * Protocol spec: CLI bootstrapping & command registration
- */
-
-/** Whether --verbose was passed (controls help detail level). */
-declare let verboseHelp: boolean;
 /** Set the verbose help flag. When false, built-in options are hidden from help. */
 declare function setVerboseHelp(verbose: boolean): void;
-/** Base URL for online documentation. Null means no docs link shown. */
-declare let docsUrl: string | null;
 /**
  * Set the base URL for online documentation links shown in help and man pages.
  * Pass null to disable. Command-level help appends `/commands/{name}` automatically.
@@ -152,18 +367,65 @@ interface OptionConfig {
     parseArg?: (value: string) => unknown;
 }
 /**
- * Build and return the top-level Commander program.
- *
- * @param extensionsDir  Path to the extensions directory (default: ./extensions)
- * @param progName       Program name shown in help (default: apcore-cli)
+ * Emit structured JSON error to stderr for AI agents.
+ */
+declare function emitErrorJson(e: unknown, exitCode: number): void;
+/**
+ * Emit human-readable error to stderr with guidance fields.
  */
-declare function createCli(extensionsDir?: string, progName?: string, verbose?: boolean): Command;
+declare function emitErrorTty(e: unknown, exitCode: number): void;
 /**
- * Optionally apply apcore-toolkit features (DisplayResolver, RegistryWriter).
+ * APCore unified client facade (apcore-js >= 0.18.0).
+ * Exposes registry and executor as top-level properties.
+ */
+interface APCore {
+    registry: Registry;
+    executor: Executor;
+}
+/** Options for createCli. */
+interface CreateCliOptions {
+    extensionsDir?: string;
+    progName?: string;
+    verbose?: boolean;
+    /**
+     * APCore unified client instance (apcore-js >= 0.18.0).
+     * Mutually exclusive with registry/executor — providing app alongside
+     * either of those will throw.
+     */
+    app?: APCore;
+    /** Pre-populated Registry instance. Skips filesystem discovery when provided. */
+    registry?: Registry;
+    /** Pre-built Executor instance. Used alongside registry. */
+    executor?: Executor;
+    /** Extra commands to register after built-in commands (FE-11 F11). */
+    extraCommands?: Command[];
+    /** Exposure filter config or instance (FE-12). */
+    expose?: Record<string, unknown> | ExposureFilter;
+    /** Path to convention-based commands directory (apcore-toolkit ConventionScanner). */
+    commandsDir?: string;
+    /** Path to binding.yaml for display overlay (apcore-toolkit DisplayResolver). */
+    bindingPath?: string;
+    /**
+     * Built-in apcli group configuration (FE-13).
+     *
+     * Accepts:
+     *  - `true` / `false` (shorthand for `{mode: "all"}` / `{mode: "none"}`)
+     *  - A config object (see {@link ApcliConfig})
+     *  - A pre-built {@link ApcliGroup} instance (Tier 1 override)
+     *
+     * When absent, Tier 3 (apcore.yaml `apcli:` block) is consulted, falling
+     * back to auto-detect: standalone → visible, embedded → hidden.
+     */
+    apcli?: ApcliConfig | ApcliGroup;
+}
+/**
+ * Build and return the top-level Commander program.
  *
- * Uses dynamic import so the dependency remains optional — if apcore-toolkit
- * is not installed, a warning is printed and the CLI continues without it.
+ * @param extensionsDirOrOpts  Path to extensions directory, or a CreateCliOptions object.
+ * @param progName       Program name shown in help (default: apcore-cli)
+ * @param verbose        Show verbose help output
  */
+declare function createCli(extensionsDirOrOpts?: string | CreateCliOptions, progName?: string, verbose?: boolean): Command;
 declare function applyToolkitIntegration(commandsDir?: string, bindingPath?: string): Promise<void>;
 /**
  * Parse argv and run the CLI. Handles top-level error catching and exit codes.
@@ -171,11 +433,18 @@ declare function applyToolkitIntegration(commandsDir?: string, bindingPath?: str
 declare function main(progName?: string): void;
 /**
  * Build a Commander Command for a single apcore module.
+ *
+ * Includes all 11 FE-11 options: --dry-run, --trace, --stream, --strategy,
+ * --approval-timeout, --approval-token, --fields, and enhanced --format choices.
  */
 declare function buildModuleCommand(moduleDef: ModuleDescriptor, executor: Executor, helpTextMaxLength?: number, cmdName?: string, verbose?: boolean): Command;
 /**
  * Validate that a module ID conforms to the expected format.
- * Pattern: [a-z][a-z0-9_]*(.[a-z][a-z0-9_])* — max 128 chars.
+ * Pattern: [a-z][a-z0-9_]*(.[a-z][a-z0-9_])* — max 192 chars.
+ *
+ * Length limit tracks PROTOCOL_SPEC §2.7 EBNF constraint #1 — bumped from
+ * 128 to 192 in spec 1.6.0-draft to accommodate Java/.NET deep-namespace
+ * FQN-derived IDs. Filesystem-safe (192 + ".binding.yaml".length = 205 < 255).
  */
 declare function validateModuleId(moduleId: string): void;
 /**
@@ -189,35 +458,54 @@ declare function collectInput(stdinFlag?: string, cliKwargs?: Record<string, unk
 declare function reconvertEnumValues(kwargs: Record<string, unknown>, options: OptionConfig[]): Record<string, unknown>;
 
 /**
- * Display overlay helpers — shared resolution logic for CLI surfaces.
- */
-
-/**
- * Extract resolved display overlay from a ModuleDescriptor's metadata.
- */
-declare function getDisplay(descriptor: ModuleDescriptor): Record<string, unknown>;
-/**
- * Return [displayName, description, tags] resolved from the display overlay.
+ * Interactive approval prompts with timeout.
  *
- * Falls back to scanner-provided values when no overlay is present.
+ * Protocol spec: Approval workflow
  */
-declare function getCliDisplayFields(descriptor: ModuleDescriptor): [string, string, string[]];
 
 /**
- * Init command — scaffold new apcore modules (Phase 1).
- */
-
+ * CLI ApprovalHandler that prompts in TTY, auto-denies in non-TTY.
+ *
+ * Implements the apcore ApprovalHandler protocol:
+ * - `requestApproval(request) -> ApprovalResult`
+ * - `checkApproval(approvalId) -> ApprovalResult`
+ *
+ * Pass to Executor via `executor.setApprovalHandler(handler)`.
+ */
+declare class CliApprovalHandler {
+    autoApprove: boolean;
+    timeout: number;
+    constructor(autoApprove?: boolean, timeout?: number);
+    requestApproval(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    checkApproval(_approvalId: string): Promise<Record<string, unknown>>;
+}
 /**
- * Register the init command group on the CLI program.
+ * Check if module requires approval and handle accordingly.
+ * Returns normally if approved (or approval not required).
+ * Throws ApprovalDeniedError or ApprovalTimeoutError on denial/timeout so the
+ * caller (buildModuleCommand action) can run audit flush and tear-down before
+ * the process exits via the shared error path.
  */
-declare function registerInitCommand(cli: Command): void;
+declare function checkApproval(moduleDef: ModuleDescriptor, autoApprove: boolean, timeout?: number): Promise<void>;
 
 /**
  * ConfigResolver — 4-tier config resolution (CLI flag > env > file > default).
  *
  * Protocol spec: Configuration resolution
  */
-/** Default configuration values. */
+/**
+ * Default configuration values.
+ *
+ * Audit D9 (config cleanup, v0.6.x): the entries `sandbox.enabled`,
+ * `cli.auto_approve`, `cli.stdin_buffer_limit`, and the eight `apcore-cli.*`
+ * namespace aliases were removed because no production code path reads
+ * them via `resolve()`. Sandbox is configured via the `--sandbox` CLI flag,
+ * auto-approve via `--yes`, the stdin buffer is hard-coded, and namespace
+ * aliases are registered separately by `apcore-js`'s Config Bus when
+ * `registerConfigNamespace()` runs at `createCli` startup. The cross-key
+ * file-lookup mechanism (`NAMESPACE_TO_LEGACY` / `LEGACY_TO_NAMESPACE`)
+ * still works regardless — it does not depend on these DEFAULTS entries.
+ */
 declare const DEFAULTS: Record<string, unknown>;
 /**
  * Register the apcore-cli Config Bus namespace (apcore >= 0.15.0).
@@ -236,6 +524,13 @@ declare class ConfigResolver {
     private readonly configPath;
     private fileCache;
     private fileCacheLoaded;
+    /**
+     * Raw parsed yaml root (pre-flatten). Populated alongside `fileCache`
+     * on load. Used by `resolveObject()` to walk nested paths without
+     * invoking `flattenDict` — see FE-13 spec §4.8 M1 note.
+     * `null` when no config file is present or parsing fails.
+     */
+    private _rawConfig;
     constructor(cliFlags?: Record<string, unknown>, configPath?: string);
     /**
      * Resolve a single configuration key across all four tiers.
@@ -245,6 +540,26 @@ declare class ConfigResolver {
      * Load a value from the config file using a dot-separated key path.
      */
     private resolveFromFile;
+    /**
+     * Resolve a configuration key to its raw nested value (FE-13).
+     *
+     * Unlike `resolve()`, this method does NOT flatten the yaml tree — it
+     * walks the dot-separated path directly against the parsed yaml root.
+     * This lets callers retrieve non-leaf structures (booleans, arrays,
+     * objects) such as the `apcli` visibility config, which is naturally
+     * shaped as a nested object in apcore.yaml.
+     *
+     * Semantics:
+     *   - Returns `null` when no config file is loaded or when the path is
+     *     not present / descends into a non-object node (including arrays).
+     *   - Returns the raw value (boolean / array / object / scalar) when the
+     *     full path resolves to a leaf or intermediate node.
+     *
+     * Intentionally DOES NOT consult DEFAULTS, env vars, or CLI flags — it is
+     * strictly a yaml-tree accessor. Scalar `resolve()` semantics are
+     * unaffected.
+     */
+    resolveObject(key: string): unknown;
     /**
      * Load and flatten a YAML config file.
      */
@@ -256,42 +571,41 @@ declare class ConfigResolver {
 }
 
 /**
- * Discovery commands — list and describe modules.
- *
- * Protocol spec: Module discovery & introspection
+ * Register the `list` subcommand on the given group (FE-13).
  */
-
+declare function registerListCommand(apcliGroup: Command, registry: Registry, exposureFilter?: ExposureFilter): void;
 /**
- * Register list and describe commands on the CLI group.
+ * Register the `describe` subcommand on the given group (FE-13).
  */
-declare function registerDiscoveryCommands(cli: Command, registry: Registry): void;
-
+declare function registerDescribeCommand(apcliGroup: Command, registry: Registry): void;
 /**
- * TTY-adaptive output formatting (table/json).
+ * Register the `exec` subcommand on the given group (FE-13).
  *
- * Protocol spec: Output formatting
- */
-
-/**
- * Resolve output format with TTY-adaptive default.
- */
-declare function resolveFormat(explicitFormat?: string): string;
-/**
- * Truncate text to maxLength, appending '...' if needed.
+ * Generic dispatch: `apcli exec <module-id> [--format fmt] [--input json]`.
+ * Unlike the per-module commands built by `buildModuleCommand`, this command
+ * does not derive options from the module's input schema — inputs are passed
+ * as a JSON object via `--input`. This mirrors the apcli-flavoured generic
+ * dispatch contract in the builtin-group feature spec.
  */
-declare function truncate(text: string, maxLength?: number): string;
+declare function registerExecCommand(apcliGroup: Command, registry: Registry, executor: Executor): void;
 /**
- * Format and print a list of modules.
+ * Register the standalone validate command.
  */
-declare function formatModuleList(modules: ModuleDescriptor[], format: string, filterTags?: string[]): void;
+declare function registerValidateCommand(cli: Command, registry: Registry, executor: Executor): void;
+
 /**
- * Format and print full module metadata.
+ * TTY-adaptive output formatting (table/json/csv/yaml/jsonl).
+ *
+ * Protocol spec: Output formatting (FE-09 enhanced)
  */
-declare function formatModuleDetail(moduleDef: ModuleDescriptor, format: string): void;
+
 /**
  * Format and print module execution result.
+ *
+ * Supports formats: json, table, csv, yaml, jsonl.
+ * The `fields` option allows dot-path field selection on dict results.
  */
-declare function formatExecResult(result: unknown, format?: string): void;
+declare function formatExecResult(result: unknown, format?: string, fields?: string): void;
 
 /**
  * JSON Schema $ref resolver.
@@ -310,17 +624,6 @@ declare function resolveRefs(schema: Record<string, unknown>, maxDepth?: number,
  * Protocol spec: Schema-driven argument parsing
  */
 
-/** Sentinel type marker for boolean flags. */
-declare const BOOLEAN_FLAG: unique symbol;
-type TypeResult = "string" | "int" | "float" | typeof BOOLEAN_FLAG | "file";
-/**
- * Map JSON Schema type to a type identifier.
- */
-declare function mapType(propName: string, propSchema: Record<string, unknown>): TypeResult;
-/**
- * Extract help text from schema property, preferring x-llm-description.
- */
-declare function extractHelp(propSchema: Record<string, unknown>, maxLength?: number): string | undefined;
 /**
  * Convert a JSON Schema `properties` object into an array of
  * Commander option configurations.
@@ -328,42 +631,86 @@ declare function extractHelp(propSchema: Record<string, unknown>, maxLength?: nu
 declare function schemaToCliOptions(schema: Record<string, unknown>, maxHelpLength?: number): OptionConfig[];
 
 /**
- * Interactive approval prompts with timeout.
+ * Shell completion + man page generation.
  *
- * Protocol spec: Approval workflow
+ * Protocol spec: Shell integration
  */
 
 /**
- * Check if module requires approval and handle accordingly.
- * Returns normally if approved (or approval not required).
- * Calls process.exit(46) if denied/timed out/non-TTY.
+ * Configure --help --man support on a Commander program.
+ * When --man is passed with --help, outputs a complete roff man page
+ * covering all registered commands (including downstream business commands).
+ *
+ * Usage in downstream projects:
+ *   configureManHelp(program, 'reach', '0.2.0', 'ReachForge: The Social Influence Engine', 'https://reachforge.dev/docs');
+ */
+declare function configureManHelp(program: Command, progName: string, version: string, description?: string, docsUrl?: string): void;
+/**
+ * Register the `completion` subcommand on `host` (typically the apcli group
+ * per spec §4.1, or the root program during the transition period).
+ *
+ * The completion-script generator enumerates the actually-registered set of
+ * subcommands from the root program's Commander tree at generation time
+ * (spec §4.13).
  */
-declare function checkApproval(moduleDef: ModuleDescriptor, autoApprove: boolean): Promise<void>;
+declare function registerCompletionCommand(host: Command): void;
 
 /**
- * Shell completion + man page generation.
+ * System management commands — health, usage, enable, disable, reload, config (FE-11 F2).
  *
- * Protocol spec: Shell integration
+ * Each registrar delegates to the corresponding system.* module via the
+ * executor. The six registrars are pure attach-only operations and are
+ * dispatched by `createCli()`'s FE-13 apcli group integration.
  */
 
 /**
- * Build a complete roff man page for the entire program.
- * Covers all registered commands including downstream business commands.
+ * Attach the `health` subcommand to the passed apcliGroup.
  */
-declare function buildProgramManPage(program: Command, progName: string, version: string, description?: string, docsUrl?: string): string;
+declare function registerHealthCommand(apcliGroup: Command, executor: Executor): void;
 /**
- * Configure --help --man support on a Commander program.
- * When --man is passed with --help, outputs a complete roff man page
- * covering all registered commands (including downstream business commands).
+ * Attach the `usage` subcommand to the passed apcliGroup.
+ */
+declare function registerUsageCommand(apcliGroup: Command, executor: Executor): void;
+/**
+ * Attach the `enable` subcommand to the passed apcliGroup.
+ */
+declare function registerEnableCommand(apcliGroup: Command, executor: Executor): void;
+/**
+ * Attach the `disable` subcommand to the passed apcliGroup.
+ */
+declare function registerDisableCommand(apcliGroup: Command, executor: Executor): void;
+/**
+ * Attach the `reload` subcommand to the passed apcliGroup.
+ */
+declare function registerReloadCommand(apcliGroup: Command, executor: Executor): void;
+/**
+ * Attach the `config` subcommand (with `get` and `set` children) to the
+ * passed apcliGroup.
  *
- * Usage in downstream projects:
- *   configureManHelp(program, 'reach', '0.2.0', 'ReachForge: The Social Influence Engine', 'https://reachforge.dev/docs');
+ * Signature note: config reads/writes go through `executor.call()` to
+ * `system.config.get` / `system.control.update_config`, so this registrar
+ * takes an {@link Executor} (not a Registry). The FE-13 dispatcher table
+ * entry for `config` sets `requiresExecutor: true` accordingly.
  */
-declare function configureManHelp(program: Command, progName: string, version: string, description?: string, docsUrl?: string): void;
+declare function registerConfigCommand(apcliGroup: Command, executor: Executor): void;
+
+/**
+ * Pipeline strategy commands — describe-pipeline (FE-11 F8).
+ */
+
 /**
- * Register completion and man commands.
+ * Register the describe-pipeline command.
  */
-declare function registerShellCommands(cli: Command, progName?: string): void;
+declare function registerPipelineCommand(cli: Command, executor: Executor): void;
+
+/**
+ * Init command — scaffold new apcore modules (Phase 1).
+ */
+
+/**
+ * Register the init command group on the CLI program.
+ */
+declare function registerInitCommand(cli: Command): void;
 
 /**
  * Error classes and exit code mapping for apcore-cli.
@@ -406,6 +753,8 @@ declare const EXIT_CODES: {
     readonly MODULE_NOT_FOUND: 44;
     readonly MODULE_LOAD_ERROR: 44;
     readonly MODULE_DISABLED: 44;
+    readonly DEPENDENCY_NOT_FOUND: 44;
+    readonly DEPENDENCY_VERSION_MISMATCH: 44;
     readonly SCHEMA_VALIDATION_ERROR: 45;
     readonly APPROVAL_DENIED: 46;
     readonly APPROVAL_TIMEOUT: 46;
@@ -416,6 +765,7 @@ declare const EXIT_CODES: {
     readonly CONFIG_NAMESPACE_RESERVED: 78;
     readonly CONFIG_NAMESPACE_DUPLICATE: 78;
     readonly CONFIG_ENV_PREFIX_CONFLICT: 78;
+    readonly CONFIG_ENV_MAP_CONFLICT: 78;
     readonly CONFIG_MOUNT_ERROR: 66;
     readonly CONFIG_BIND_ERROR: 65;
     readonly ERROR_FORMATTER_DUPLICATE: 70;
@@ -440,10 +790,6 @@ declare const LEVELS: {
 type LogLevel = keyof typeof LEVELS;
 declare function setLogLevel(level: string): void;
 declare function getLogLevel(): LogLevel;
-declare function debug(message: string): void;
-declare function info(message: string): void;
-declare function warn(message: string): void;
-declare function error(message: string): void;
 
 /**
  * AuditLogger — JSONL audit trail.
@@ -462,6 +808,7 @@ declare function getAuditLogger(): AuditLogger | null;
 declare class AuditLogger {
     static readonly DEFAULT_PATH: string;
     private readonly logPath;
+    private writeFailureWarned;
     constructor(path?: string);
     private ensureDirectory;
     logExecution(moduleId: string, inputData: Record<string, unknown>, status: ExecutionStatus, exitCode: number, durationMs: number): void;
@@ -469,19 +816,31 @@ declare class AuditLogger {
     private getUser;
 }
 
-/**
- * ConfigEncryptor — Keyring + AES-256-GCM fallback.
- *
- * Protocol spec: Security — config encryption
- */
 /**
  * Encrypts and decrypts configuration values. Prefers OS keyring for key
- * storage, falling back to AES-256-GCM with a derived key.
+ * storage, falling back to AES-256-GCM with a key derived from
+ * APCORE_CLI_CONFIG_PASSPHRASE when set, or from hostname+username
+ * (obfuscation-only) as a last resort.
+ *
+ * Wire format v2: enc:v2:<base64(salt(16)+nonce(12)+tag(16)+ciphertext)>
+ * Legacy format:  enc:<base64(nonce(12)+tag(16)+ciphertext)>  (read-only)
  */
 declare class ConfigEncryptor {
     static readonly SERVICE_NAME = "apcore-cli";
+    private static weakFallbackWarned;
     /**
      * Encrypt and store a configuration value.
+     *
+     * Cross-SDK contract (D10-003, 2026-04-26): when the OS keyring is
+     * detected as available but `setPassword` then throws (locked keyring,
+     * transient backend failure, permission revoked, etc.), the error is
+     * propagated wrapped in a `ConfigDecryptionError`. Previously TS
+     * caught the exception and silently fell through to AES file encryption
+     * — a quiet downgrade that surprised users who expected a hard failure.
+     * Python lets the keyring exception propagate raw; Rust returns
+     * `ConfigDecryptionError::KeyringError`. The fall-through to AES is
+     * still reached when `getKeytar()` returns `null` (keyring
+     * genuinely unavailable on this platform / install).
      */
     store(key: string, value: string): Promise<string>;
     /**
@@ -491,6 +850,8 @@ declare class ConfigEncryptor {
     private deriveKey;
     private aesEncrypt;
     private aesDecrypt;
+    /** Decrypt legacy v1-format values: nonce(12)+tag(16)+ct, static salt. */
+    private aesDecryptV1;
 }
 
 /**
@@ -513,6 +874,15 @@ declare class AuthProvider {
     getApiKey(): Promise<string | null>;
     /**
      * Add authentication headers to an outgoing request.
+     *
+     * Cross-SDK contract (D10-002, 2026-04-26): the input `headers` object
+     * is mutated **in place** and the same reference is returned. Callers
+     * that share the headers reference (the documented pattern in
+     * apcore-cli/docs/features/security.md §AuthProvider) can read
+     * `headers.Authorization` after the call without re-binding the
+     * return value. Python and Rust both mutate-and-return; TS previously
+     * spread into a new object, which silently broke shared-reference
+     * callers.
      */
     authenticateRequest(headers: Record<string, string>): Promise<Record<string, string>>;
     /**
@@ -524,23 +894,31 @@ declare class AuthProvider {
 /**
  * Sandbox — Subprocess isolation for module execution.
  *
- * Protocol spec: Security — sandboxed execution
+ * Protocol spec: Security — sandboxed execution (tech-design §8.6.4).
+ *
+ * Uses a re-exec model: spawns `node <this-binary> --internal-sandbox-runner
+ * <module_id>` with a stripped environment and isolated HOME/TMPDIR.
+ * The child reads JSON from stdin, runs the module via a fresh
+ * Registry+Executor, and writes JSON to stdout.
  */
 
 /**
  * Executes modules in an isolated subprocess to limit the blast radius
  * of untrusted or third-party modules.
  *
- * When disabled, delegates directly to the Executor.
+ * When disabled (the default), delegates directly to the Executor.
+ * When enabled, spawns a restricted child process via re-exec with
+ * `--internal-sandbox-runner <module_id>`.
  */
 declare class Sandbox {
     private readonly enabled;
-    constructor(enabled?: boolean);
+    private readonly timeoutSeconds;
+    constructor(enabled?: boolean, timeoutSeconds?: number);
     /**
      * Execute a module, optionally inside a sandboxed subprocess.
      */
     execute(moduleId: string, inputData: Record<string, unknown>, executor: Executor): Promise<unknown>;
-    private sandboxedExecute;
+    private _sandboxedExecute;
 }
 
-export { ApprovalDeniedError, ApprovalTimeoutError, AuditLogger, AuthProvider, AuthenticationError, BUILTIN_COMMANDS, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, DEFAULTS, EXIT_CODES, type Executor, type ExitCode, GroupedModuleGroup, LazyGroup, LazyModuleGroup, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type Registry, Sandbox, SchemaValidationError, applyToolkitIntegration, buildModuleCommand, buildProgramManPage, checkApproval, collectInput, configureManHelp, createCli, debug, docsUrl, error, exitCodeForError, extractHelp, formatExecResult, formatModuleDetail, formatModuleList, getAuditLogger, getCliDisplayFields, getDisplay, getLogLevel, info, main, mapType, reconvertEnumValues, registerConfigNamespace, registerDiscoveryCommands, registerInitCommand, registerShellCommands, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setDocsUrl, setLogLevel, setVerboseHelp, truncate, validateModuleId, verboseHelp, warn };
+export { type APCore, type ApcliConfig, ApcliGroup, type ApcliMode, ApprovalDeniedError, ApprovalTimeoutError, AuditLogger, AuthProvider, AuthenticationError, CliApprovalHandler, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, type CreateCliOptions, DEFAULTS, EXIT_CODES, type Executor, type ExitCode, ExposureFilter, GroupedModuleGroup, LazyGroup, LazyModuleGroup, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type PipelineTrace, type PipelineTraceStep, type PreflightCheck, type PreflightResult, RESERVED_GROUP_NAMES, type Registry, Sandbox, SchemaValidationError, type StrategyInfo, type StrategyStep, applyToolkitIntegration, buildModuleCommand, checkApproval, collectInput, configureManHelp, createCli, emitErrorJson, emitErrorTty, exitCodeForError, formatExecResult, getAuditLogger, getLogLevel, main, reconvertEnumValues, registerCompletionCommand, registerConfigCommand, registerConfigNamespace, registerDescribeCommand, registerDisableCommand, registerEnableCommand, registerExecCommand, registerHealthCommand, registerInitCommand, registerListCommand, registerPipelineCommand, registerReloadCommand, registerUsageCommand, registerValidateCommand, resolveRefs, schemaToCliOptions, setAuditLogger, setDocsUrl, setLogLevel, setVerboseHelp, validateModuleId };