apcore-cli 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -37,6 +37,18 @@ declare class ExposureFilter {
  * 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.
  *
@@ -57,7 +69,12 @@ type ApcliConfig = boolean | {
     exclude?: string[];
     disableEnv?: boolean;
 };
-/** Set of group names reserved by apcore-cli (checked in cli.ts). */
+/**
+ * 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.
@@ -73,7 +90,15 @@ declare class ApcliGroup {
     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 })`.
      *
@@ -81,6 +106,7 @@ declare class ApcliGroup {
      */
     static fromCliConfig(config: ApcliConfig | undefined, opts: {
         registryInjected: boolean;
+        name?: string;
     }): ApcliGroup;
     /**
      * Tier 3 constructor — config came from `apcore.yaml`.
@@ -89,6 +115,7 @@ declare class ApcliGroup {
      */
     static fromYaml(config: unknown, opts: {
         registryInjected: boolean;
+        name?: string;
     }): ApcliGroup;
     /**
      * Non-panicking Tier 3 factory (A-001 parity with Rust's `try_from_yaml`).
@@ -97,6 +124,7 @@ declare class ApcliGroup {
      */
     static tryFromYaml(config: unknown, opts: {
         registryInjected: boolean;
+        name?: string;
     }): [ApcliGroup, null] | [null, string];
     private static _build;
     /**
@@ -336,6 +364,17 @@ declare class GroupedModuleGroup extends LazyModuleGroup {
     isGroupMapBuilt(): boolean;
 }
 
+/**
+ * Validate that a module ID conforms to the expected format.
+ *
+ * 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;
+
 /** Set the verbose help flag. When false, built-in options are hidden from help. */
 declare function setVerboseHelp(verbose: boolean): void;
 /**
@@ -366,14 +405,6 @@ interface OptionConfig {
     /** Parser function for Commander (e.g. parseInt, parseFloat). */
     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.
- */
-declare function emitErrorTty(e: unknown, exitCode: number): void;
 /**
  * APCore unified client facade (apcore-js >= 0.18.0).
  * Exposes registry and executor as top-level properties.
@@ -405,6 +436,17 @@ interface CreateCliOptions {
     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).
      *
@@ -417,6 +459,34 @@ interface CreateCliOptions {
      * 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.
@@ -426,7 +496,16 @@ interface CreateCliOptions {
  * @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>;
+/** 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.
  */
@@ -438,15 +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 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;
+
 /**
  * Collect module input from stdin and/or CLI keyword arguments.
  */
@@ -594,11 +665,25 @@ declare function registerExecCommand(apcliGroup: Command, registry: Registry, ex
 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;
+/**
+ * Format and print a list of modules.
+ */
+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): Promise<void>;
 /**
  * Format and print module execution result.
  *
@@ -911,9 +996,30 @@ declare class AuthProvider {
  * `--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;
     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.
      */
@@ -921,4 +1027,4 @@ declare class Sandbox {
     private _sandboxedExecute;
 }
 
-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 };
+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 };