apcore-cli 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -1,5 +1,174 @@
 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.
+ */
+/**
+ * Thrown for invalid built-in apcli group configuration (e.g. invalid
+ * `builtinGroupName` regex match). Cross-SDK parity with Rust's
+ * `ApcliGroupError` (D1-info-1, 2026-05-08).
+ *
+ * Extends `Error` so existing `catch (e)` blocks continue to work via
+ * `instanceof Error`; callers that want to distinguish apcli config
+ * errors from generic errors can switch on `instanceof ApcliGroupError`.
+ */
+declare class ApcliGroupError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 when no rename is configured.
+ * Default mirrors {@link DEFAULT_BUILTIN_GROUP_NAME}; when `builtinGroupName`
+ * is overridden the live reserved set is `new Set([apcliGroup.name])` and
+ * is applied per-instance during the cli.ts collision check.
+ */
+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 readonly _name;
+    private constructor();
+    /**
+     * Resolved name for the built-in command group (default `"apcli"`).
+     * Overridable via createCli's `builtinGroupName` option for downstream
+     * branded CLIs that want a custom namespace. Cross-SDK parity with
+     * Python `ApcliGroup.name` (2026-05-08).
+     */
+    get name(): string;
+    /**
+     * 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;
+        name?: string;
+    }): 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;
+        name?: string;
+    }): 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;
+        name?: string;
+    }): [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,7 +183,21 @@ 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. */
@@ -27,33 +210,45 @@ interface Executor {
     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 {
-    check: string;
-    passed: boolean;
-    error?: unknown;
-    warnings?: string[];
+    readonly check: string;
+    readonly passed: boolean;
+    readonly error?: unknown;
+    readonly warnings?: string[];
 }
-/** Result of executor.validate(). */
+/** Result of executor.validate() — parity with apcore-js PreflightResult. */
 interface PreflightResult {
-    valid: boolean;
-    requires_approval: boolean;
-    checks: PreflightCheck[];
+    readonly valid: boolean;
+    readonly requiresApproval: boolean;
+    readonly checks: readonly PreflightCheck[];
+    readonly errors?: ReadonlyArray<Record<string, unknown>>;
 }
-/** A single step in a pipeline trace. */
+/** A single step in a pipeline trace — parity with apcore-js StepTrace. */
 interface PipelineTraceStep {
-    name: string;
-    duration_ms: number;
-    skipped: boolean;
-    skip_reason?: string;
+    readonly name: string;
+    readonly durationMs: number;
+    readonly skipped: boolean;
+    readonly skipReason?: string | null;
 }
-/** Pipeline execution trace returned by callWithTrace(). */
+/** Pipeline execution trace returned by callWithTrace() — parity with apcore-js PipelineTrace. */
 interface PipelineTrace {
-    strategy_name: string;
-    total_duration_ms: number;
-    success: boolean;
-    steps: PipelineTraceStep[];
+    readonly moduleId?: string;
+    readonly strategyName: string;
+    readonly totalDurationMs: number;
+    readonly success: boolean;
+    readonly steps: readonly PipelineTraceStep[];
 }
 /** Placeholder for apcore-js ModuleDescriptor. */
 interface ModuleDescriptor {
@@ -67,8 +262,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.
  */
@@ -124,6 +317,16 @@ 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.
      *
@@ -135,10 +338,18 @@ declare class GroupedModuleGroup extends LazyModuleGroup {
     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[];
     /**
@@ -154,20 +365,18 @@ declare class GroupedModuleGroup extends LazyModuleGroup {
 }
 
 /**
- * CLI entry point — createCli / main equivalents.
+ * Validate that a module ID conforms to the expected format.
  *
- * Protocol spec: CLI bootstrapping & command registration
- * Implements: F1 (dry-run), F3 (enhanced errors), F4 (trace),
- * F5 (approval handler), F6 (stream), F8 (strategy), F9 (output formats),
- * F11 (extra commands)
+ * Pattern: `[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*` — max 192 chars.
+ *
+ * On invalid input, writes a human-readable error to stderr and calls
+ * `process.exit(EXIT_CODES.INVALID_CLI_INPUT)`. Cross-SDK parity with Python
+ * `apcore_cli.validate.validate_module_id` and Rust `validate_module_id`.
  */
+declare function validateModuleId(moduleId: string): void;
 
-/** 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.
@@ -197,24 +406,87 @@ interface OptionConfig {
     parseArg?: (value: string) => unknown;
 }
 /**
- * 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.
+ * APCore unified client facade (apcore-js >= 0.18.0).
+ * Exposes registry and executor as top-level properties.
  */
-declare function emitErrorTty(e: unknown, exitCode: number): void;
+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;
+    /**
+     * Optional allowlist of module-path prefixes forwarded to
+     * apcore-toolkit's `RegistryWriter.write` when registering convention-scanned
+     * or binding-loaded modules. When set, the writer rejects any `target:`
+     * path outside the listed prefixes — mitigates arbitrary-code-execution via
+     * forged binding YAML (e.g. `target: "os:system"`).
+     *
+     * Mirrors the Python SDK's `allowed_prefixes` kwarg
+     * (apcore-cli-python/src/apcore_cli/factory.py).
+     */
+    allowedPrefixes?: 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;
+    /**
+     * Override the name of the built-in command group (default `"apcli"`).
+     * Downstream branded CLIs that want their built-ins under a custom
+     * namespace (e.g. `mycorp-cli admin health`) pass a different value
+     * here. Must match `/^[a-z][a-z0-9_-]*$/` — non-empty, lowercase,
+     * alphanumeric + `_` / `-`. Invalid values cause exit code 2.
+     *
+     * Note: env var `APCORE_CLI_APCLI` and config keys `apcli.*` remain
+     * stable regardless of this rename — they are apcore-cli-internal
+     * toggles, not user-facing. Mirrors Python
+     * `create_cli(builtin_group_name=)`. Cross-SDK parity: 2026-05-08.
+     */
+    builtinGroupName?: string;
+    /**
+     * Host application version printed by `-V, --version`.
+     *
+     * When omitted, the `--version` flag is NOT registered — embedded CLIs
+     * that do not opt in will not surface the SDK's own version. The
+     * standalone `apcore-cli` binary entry point passes its package version
+     * explicitly (see `main()`).
+     */
+    version?: string;
+    /**
+     * Top-level CLI description shown at the head of `--help`. Defaults to
+     * `${progName} CLI` when omitted, so embedded CLIs do not leak the
+     * "apcore" framework name into their own help output.
+     */
+    description?: string;
 }
 /**
  * Build and return the top-level Commander program.
@@ -224,13 +496,16 @@ interface CreateCliOptions {
  * @param verbose        Show verbose help output
  */
 declare function createCli(extensionsDirOrOpts?: string | CreateCliOptions, progName?: string, verbose?: boolean): Command;
-/**
- * Optionally apply apcore-toolkit features (DisplayResolver, RegistryWriter).
- *
- * Uses dynamic import so the dependency remains optional — if apcore-toolkit
- * is not installed, a warning is printed and the CLI continues without it.
- */
-declare function applyToolkitIntegration(commandsDir?: string, bindingPath?: string): Promise<void>;
+/** Options bag for {@link applyToolkitIntegration}. */
+interface ApplyToolkitIntegrationOptions {
+    /**
+     * Allowlist of module-path prefixes forwarded to apcore-toolkit's
+     * `RegistryWriter.write` when registering scanned/loaded modules. Mirrors
+     * the Python factory's `allowed_prefixes` kwarg.
+     */
+    allowedPrefixes?: string[];
+}
+declare function applyToolkitIntegration(commandsDir?: string, bindingPath?: string, options?: ApplyToolkitIntegrationOptions): Promise<void>;
 /**
  * Parse argv and run the CLI. Handles top-level error catching and exit codes.
  */
@@ -242,11 +517,7 @@ declare function main(progName?: string): void;
  * --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.
- */
-declare function validateModuleId(moduleId: string): void;
+
 /**
  * Collect module input from stdin and/or CLI keyword arguments.
  */
@@ -282,40 +553,30 @@ declare class CliApprovalHandler {
 /**
  * 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.
+ * 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 checkApproval(moduleDef: ModuleDescriptor, autoApprove: boolean, timeout?: number): Promise<void>;
 
 /**
- * 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.
+ * ConfigResolver — 4-tier config resolution (CLI flag > env > file > default).
  *
- * Falls back to scanner-provided values when no overlay is present.
- */
-declare function getCliDisplayFields(descriptor: ModuleDescriptor): [string, string, string[]];
-
-/**
- * Init command — scaffold new apcore modules (Phase 1).
- */
-
-/**
- * Register the init command group on the CLI program.
+ * Protocol spec: Configuration resolution
  */
-declare function registerInitCommand(cli: Command): void;
-
 /**
- * ConfigResolver — 4-tier config resolution (CLI flag > env > file > default).
+ * Default configuration values.
  *
- * Protocol spec: Configuration resolution
+ * 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.
  */
-/** Default configuration values. */
 declare const DEFAULTS: Record<string, unknown>;
 /**
  * Register the apcore-cli Config Bus namespace (apcore >= 0.15.0).
@@ -334,6 +595,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.
@@ -343,6 +611,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.
      */
@@ -354,42 +642,48 @@ declare class ConfigResolver {
 }
 
 /**
- * Discovery commands — list, describe, validate (FE-04, FE-11).
- *
- * 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;
+/**
+ * Register the `exec` subcommand on the given group (FE-13).
+ *
+ * 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 registerExecCommand(apcliGroup: Command, registry: Registry, executor: Executor): void;
 /**
  * Register the standalone validate command.
  */
 declare function registerValidateCommand(cli: Command, registry: Registry, executor: Executor): void;
 
 /**
- * TTY-adaptive output formatting (table/json/csv/yaml/jsonl).
+ * TTY-adaptive output formatting (table/json/csv/yaml/jsonl/markdown/skill).
  *
- * Protocol spec: Output formatting (FE-09 enhanced)
+ * Protocol spec: Output formatting (FE-08 / FE-09 enhanced)
  */
 
 /**
  * Resolve output format with TTY-adaptive default.
  */
 declare function resolveFormat(explicitFormat?: string): string;
-/**
- * Truncate text to maxLength, appending '...' if needed.
- */
-declare function truncate(text: string, maxLength?: number): string;
 /**
  * Format and print a list of modules.
  */
-declare function formatModuleList(modules: ModuleDescriptor[], format: string, filterTags?: string[], showDeps?: boolean): void;
+declare function formatModuleList(modules: ModuleDescriptor[], format: string, filterTags?: string[], showDeps?: boolean, exposureFilter?: {
+    isExposed(moduleId: string): boolean;
+}): Promise<void>;
 /**
  * Format and print full module metadata.
  */
-declare function formatModuleDetail(moduleDef: ModuleDescriptor, format: string): void;
+declare function formatModuleDetail(moduleDef: ModuleDescriptor, format: string): Promise<void>;
 /**
  * Format and print module execution result.
  *
@@ -397,14 +691,6 @@ declare function formatModuleDetail(moduleDef: ModuleDescriptor, format: string)
  * The `fields` option allows dot-path field selection on dict results.
  */
 declare function formatExecResult(result: unknown, format?: string, fields?: string): void;
-/**
- * Format and print a PreflightResult to stdout.
- */
-declare function formatPreflightResult(result: PreflightResult, format?: string): void;
-/**
- * Return the exit code for the first failed check in a PreflightResult.
- */
-declare function firstFailedExitCode(result: PreflightResult): number;
 
 /**
  * JSON Schema $ref resolver.
@@ -423,17 +709,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.
@@ -446,11 +721,6 @@ declare function schemaToCliOptions(schema: Record<string, unknown>, maxHelpLeng
  * Protocol spec: Shell integration
  */
 
-/**
- * Build a complete roff man page for the entire program.
- * Covers all registered commands including downstream business commands.
- */
-declare function buildProgramManPage(program: Command, progName: string, version: string, description?: string, docsUrl?: string): string;
 /**
  * Configure --help --man support on a Commander program.
  * When --man is passed with --help, outputs a complete roff man page
@@ -461,21 +731,53 @@ declare function buildProgramManPage(program: Command, progName: string, version
  */
 declare function configureManHelp(program: Command, progName: string, version: string, description?: string, docsUrl?: string): void;
 /**
- * Register completion and man commands.
+ * 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 registerShellCommands(cli: Command, progName?: string): void;
+declare function registerCompletionCommand(host: Command): void;
 
 /**
  * System management commands — health, usage, enable, disable, reload, config (FE-11 F2).
  *
- * Each delegates to system.* modules via executor.
- * No-op if system modules are unavailable (graceful probe).
+ * 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.
  */
 
 /**
- * Register system management commands. No-op if system modules are not available.
+ * Attach the `health` subcommand to the passed apcliGroup.
+ */
+declare function registerHealthCommand(apcliGroup: Command, executor: Executor): void;
+/**
+ * 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.
+ *
+ * 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 registerSystemCommands(cli: Command, executor: Executor): Promise<void>;
+declare function registerConfigCommand(apcliGroup: Command, executor: Executor): void;
 
 /**
  * Pipeline strategy commands — describe-pipeline (FE-11 F8).
@@ -486,6 +788,15 @@ declare function registerSystemCommands(cli: Command, executor: Executor): Promi
  */
 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.
  *
@@ -527,6 +838,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;
@@ -562,10 +875,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.
@@ -584,6 +893,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;
@@ -591,19 +901,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>;
     /**
@@ -613,6 +935,8 @@ declare class ConfigEncryptor {
     private deriveKey;
     private aesEncrypt;
     private aesDecrypt;
+    /** Decrypt legacy v1-format values: nonce(12)+tag(16)+ct, static salt. */
+    private aesDecryptV1;
 }
 
 /**
@@ -635,6 +959,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>>;
     /**
@@ -646,23 +979,52 @@ 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 {
+    /** Default post-capture stdout+stderr byte budget for sandboxed children. */
+    static readonly DEFAULT_MAX_OUTPUT_BYTES: number;
     private readonly enabled;
-    constructor(enabled?: boolean);
+    private readonly timeoutSeconds;
+    private extensionsRoot;
+    private maxOutputBytes;
+    constructor(enabled?: boolean, timeoutSeconds?: number);
+    /**
+     * Set the extensions root that is forwarded to the sandboxed runner via
+     * `APCORE_EXTENSIONS_ROOT`. The path is resolved to absolute when injected
+     * so the child (whose cwd is the fresh sandbox tempdir) can locate modules.
+     *
+     * Builder-style — returns `this` so call sites can chain. Mirrors Python's
+     * `Sandbox.with_extensions_root` (D1-004 cross-SDK parity).
+     */
+    withExtensionsRoot(extensionsRoot: string | null): this;
+    /**
+     * Cap the post-capture stdout+stderr byte budget for the sandboxed
+     * subprocess. Default: 64 MiB (`Sandbox.DEFAULT_MAX_OUTPUT_BYTES`).
+     *
+     * Builder-style — returns `this`. Mirrors Python's
+     * `Sandbox.with_max_output_bytes` (D1-004 cross-SDK parity).
+     */
+    withMaxOutputBytes(maxOutputBytes: number): this;
     /**
      * 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, CliApprovalHandler, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, type CreateCliOptions, DEFAULTS, EXIT_CODES, type Executor, type ExitCode, GroupedModuleGroup, LazyGroup, LazyModuleGroup, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type PipelineTrace, type PipelineTraceStep, type PreflightCheck, type PreflightResult, type Registry, Sandbox, SchemaValidationError, applyToolkitIntegration, buildModuleCommand, buildProgramManPage, checkApproval, collectInput, configureManHelp, createCli, debug, docsUrl, emitErrorJson, emitErrorTty, error, exitCodeForError, extractHelp, firstFailedExitCode, formatExecResult, formatModuleDetail, formatModuleList, formatPreflightResult, getAuditLogger, getCliDisplayFields, getDisplay, getLogLevel, info, main, mapType, reconvertEnumValues, registerConfigNamespace, registerDiscoveryCommands, registerInitCommand, registerPipelineCommand, registerShellCommands, registerSystemCommands, registerValidateCommand, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setDocsUrl, setLogLevel, setVerboseHelp, truncate, validateModuleId, verboseHelp, warn };
+export { type APCore, type ApcliConfig, ApcliGroup, ApcliGroupError, type ApcliMode, type ApplyToolkitIntegrationOptions, 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, exitCodeForError, formatExecResult, formatModuleDetail, formatModuleList, getAuditLogger, getLogLevel, main, reconvertEnumValues, registerCompletionCommand, registerConfigCommand, registerConfigNamespace, registerDescribeCommand, registerDisableCommand, registerEnableCommand, registerExecCommand, registerHealthCommand, registerInitCommand, registerListCommand, registerPipelineCommand, registerReloadCommand, registerUsageCommand, registerValidateCommand, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setDocsUrl, setLogLevel, setVerboseHelp, validateModuleId };