Repository navigation
External completion sources: Carapace, Fig-compatible specs and Inshellisense #142
Description
Goal
Decide which external structured completion sources NMSh should support, and how, without giving up its own UI.
Carapace
https://github.com/carapace-sh/carapace-bin (MIT, Go) — a multi-shell completion engine with a large command library and a spec format (carapace-spec).
- Can NMSh query it as an external source (structured export output) per request?
- Latency and caching per keystroke.
- Coverage vs. the zsh capture helper; how descriptions and groups map to Rich completion and CLI IntelliSense system #140's model.
Fig-compatible specs
Declarative specs: command, subcommands, options, args, dynamic values (generators), descriptions.
- Format and ecosystem status (https://github.com/withfig/autocomplete).
- Licensing: do not assume every third-party spec is license-compatible. Verify before any reuse.
- Security: generators run commands. Define what, if anything, NMSh may execute (bounded, never partial user input).
Inshellisense
https://github.com/microsoft/inshellisense (MIT, TypeScript) — IDE-like CLI autocomplete built on Fig-style specs.
- Architecture ideas worth adopting.
- Whether any parser/spec abstractions fit NMSh.
- License compatibility.
- Interop vs independent implementation.
No code is copied in this research.
Deliverable
- Findings comment comparing the three, with a recommended first external source, licensing notes, and a security model for dynamic generators.
- Follow-up implementation issue(s) only for the chosen direction.
Dependencies / related
Part of #140. Related #84, #9 (installing Carapace needs explicit confirmation).
Activity
raiseCatError commentedon Sep 30, 2026
Research decision for v0.8: retain native zsh as the only enabled completion source. No upstream code was copied and no tool was installed.
Carapace supports configured shell bridges (bridge documentation) and its Git completer includes callback/action paths. Timeout, cancellation and output caps limit resource use but do not prevent a generator from mutating files or using the network. No proven universal static-only switch was established. Disable bridges/custom configuration in any future adapter and audit an allowlist of completion paths before claiming bounded local behavior. Never query arbitrary unknown executables with --help.
Latency: Carapace and Inshellisense are absent from this environment, so no local cold/warm measurements exist. Upstream examples are not NMSh benchmarks. A future adapter must measure cold process startup, warm repeated queries, realistic commands/cwds and slow generator cancellation. Cache by executable/provider version, cwd and parsed context with bounded retention; never reuse a stale buffer's replacement range. Current native cold capture measured about 227ms (Git) / 84ms (commands); 500-candidate local filtering p95 0.13ms.
Licensing: Carapace, Fig repository, and Inshellisense declare MIT. Preserve notices and audit each chosen spec/dependency at a pinned revision; a repository-level license is not proof that every third-party spec or asset is acceptable. No reuse decision is made here. Inshellisense's current package manifest declares Node >=18 and <23 and carries its own runtime/PTY dependencies, so embedding it is a poor fit for NMSh's Node 22/26 targets.
Strict dynamic-generator boundary: disabled by default; no eval/import of third-party executable specs, composer execution, shell substitution, cloud requests or automatic installation. Future opt-in support requires an explicit audited operation allowlist, argv-only invocation, detached process-group isolation, cancellation, hard timeout/output bounds and a stated local read-only contract. Arbitrary JavaScript callbacks cannot satisfy this contract merely by setting a timeout.
No external source is demonstrated safe and bounded enough to implement in this stack, so no follow-up issue is created. #52 remains parked. #142 remains open under the milestone's release policy.
raiseCatError commentedon Oct 4, 2026
Implemented on the v0.16 branch (PR #303,
feature/v016-platform-portability-agents). Research complete. Findings are indocs/design/command-intelligence.md; the outcome shipped in v0.16 as a bundled static completion catalog generated from withfig/autocomplete and carapace-bin (assets/completion/,provenance.json, upstream notices inlicenses/); upstream generators and callbacks are never executed. It was part of the integrated build the maintainer physically validated in the earlier v0.16 QA pass; closing with the implementation.