Technical implementation: feature tree, functional lib, and live autocomplete

Technical implementation: feature tree, functional lib, and live autocomplete

Summary

Reorganize 1ls into clear feature modules, build a dependency-free functional lib, and extend the existing tooltip flow into fast, session-safe terminal autocomplete.

This is a source and implementation cleanup, not a new product architecture. The existing parser, detector, daemon, cache, tooltip, and Zsh/ZLE flow remain the foundation.

Decisions

• Perform a deliberate whole-tree migration. No compatibility re-exports are needed because the project has no current users.

• Use this feature set:

  lib, fs, ac, dx, providers, obs, cli, config, tui, cs, ex, nv, lx, fmt
  

• Use this minimum structure for each feature:

  src/[feature]/
    index.ts
    constants.ts
    types.ts
    utils.ts
  

• Keep 1ls dependency-free at runtime. Implement the useful ideas from Remeda and Effect-TS internally with tests and references.

• Use Remeda-style currying, data-last helpers, pipe, piped, compose, collection transforms, and named pipeline steps.

• Use Effect-style stateful/effectful iteration for iterate and ordered steps. Do not add the Effect package or copy an unstable API name.

• Keep the existing full-screen TUI separate from the inline tooltip/autocomplete experience.

Source migration

Current area	Target
src/browser	src/cs
src/file	src/fs
src/completer, src/completion, src/completions	src/ac
src/tooltip/completion	src/ac
src/tooltip	src/dx
src/expression, src/shortcuts	src/ex
src/navigator	src/nv
src/lexer	src/lx
src/formats, src/formatter, src/formatting	src/fmt
src/logger.ts	src/obs
src/qjs	src/cs/qjs

Update all imports and tests as each feature moves. Remove the old directories after their replacements pass.

Functional lib

Add src/lib/{index,constants,types,utils}.ts and focused tests.

Initial Remeda-inspired helpers:

pipe, piped, compose, curry
map, filter, flatMap, find, reduce
when, tap

Initial Effect-inspired concepts:

iterate, step, steps

iterate must make state, sequencing, stop conditions, and results explicit. It is for repeated state transitions and daemon/provider workflows, not ordinary array mapping. Add async or cancellation behavior only when a real filesystem or daemon use requires it.

Autocomplete and daemon implementation

Providers

Add src/providers/{index,constants,types,utils}.ts for source/query providers:

• detect paths, pipes, quoted queries, .property, and data["key"] contexts;
• inspect static JSON-like and constants-like sources safely;
• maintain source snapshots and invalidate them outside the keystroke path;
• never execute arbitrary JavaScript for source discovery.

Autocomplete

Add src/ac/{index,constants,types,utils}.ts for:

• active buffer/cursor context;
• contextual candidates and previews;
• property/method completion;
• exact replacement ranges.

Completion results must return an editor-safe edit:

type CompletionEdit = {
  label: string;
  insertText: string;
  replace: { start: number; end: number };
};

ZLE must apply that range rather than using shell heuristics such as ${BUFFER%.*}.

Developer experience

Move the existing tooltip daemon, renderer, shell adapter, and completion bridge into src/dx/.

• Make transport, selection, tooltip state, and request IDs session-scoped.
• Preserve normal shell behavior whenever the popup is hidden.
• Keep Tab/Right acceptance cursor-safe.
• Preserve ANSI redraw and scrollback behavior.
• Replace direct Bun.file usage in the daemon with portable Node APIs.

Legibility tooling

Add eslint-plugin-legibility@0.3.3 as a development dependency and configure it through Oxlint JavaScript plugins in .oxlintrc.json.

Add a changed-file script using:

npx --package eslint-plugin-legibility@0.3.3 lint-changed --comments=forbid

Use the plugin to enforce small functions, shallow control flow, named intermediate values, readable array chains, and no quadratic patterns. It must not be a runtime dependency.

Implementation order

1. Record baseline typecheck, lint, and focused tooltip tests.
2. Add legibility tooling and the feature skeleton.
3. Implement and test lib.
4. Migrate lx, ex, nv, fmt, and fs.
5. Add providers and ac contracts.
6. Migrate and deepen dx.
7. Add config and obs.
8. Update cli, cs, and tui imports.
9. Remove stale directories and global daemon shortcuts.
10. Run full validation and benchmarks.

Testing and performance

Run the narrowest check after each phase:

bun run typecheck
bun run lint
bun run lint:legibility
focused unit tests
cross-feature tests

Then run:

bun run build
bun test
bun run test:integration
exact Bun 1.4 container checks
scriptc vs Bun vs jq vs fx benchmarks

Initial performance targets:

Operation	Target
ZLE sensing/request construction	< 1 ms
Warm autocomplete response	~8 ms p95
Tooltip repaint	< 16 ms
Source parsing	off the keystroke path
Dropped or blocked keystrokes	0

Acceptance criteria

• The source tree follows the feature map with no stale old directories or imports.
• lib is dependency-free, tested, and used by multiple features.
• The Zsh flow recognizes both 1ls and non-1ls data queries.
• Suggestions appear automatically when deterministic source/query evidence exists.
• Acceptance replaces only the active token and preserves text after the cursor.
• Hidden popups do not hijack normal shell keys.
• Two terminal sessions do not share selection, response, or tooltip state.
• File changes update the source snapshot without blocking typing.
• eslint-plugin-legibility, typecheck, lint, unit tests, integration tests, Bun 1.4 validation, and benchmarks pass.

Start by recording the baseline with bun run typecheck, bun run lint, and the focused tooltip tests. Then follow the stated implementation order from .oxlintrc.json and the src feature map, adding focused tests as lib, providers, ac, and dx are introduced. Done means the old directories and imports are removed, the listed validation commands pass, and the acceptance criteria and performance targets are met.