lantern

oculus-cli-cleanup-analysis

Oculus CLI Cleanup Analysis

Current State

The oculus CLI has grown to 3226 lines with 45+ commands, far beyond the 3-operation ISA defined in wanderland-isa.

Problems

1. Command Explosion

Tag Commands (7 total):

  • tag - Add tags
  • add-tag - Add a tag
  • tags - Get tags
  • untag - Remove tags
  • remove-tag - Remove a tag
  • retag - Set/replace tags
  • find-tag - Find nodes by tag
  • list-tags - List all tags

Should be: oculus poke <slug> tags --add foo or oculus peek <slug> tags

2. Metadata Scattered

  • Separate metadata group with get/set/edit
  • Should be unified under peek/poke

3. Versioning Duplication

  • history - Show version history
  • versions - List versions
  • version - View specific version
  • diff - Show diff
  • rollback - Rollback version

4. Navigation Redundancy

  • look - View current location
  • current - Print current slug
  • last - Print previous slug

5. Specialized Commands

Many one-off commands that could be fence execute operations:

  • code - Extract code blocks
  • headers - List headers
  • stuffy-download - Download from stuffy
  • trail - Show breadcrumb trail
  • annotations - List annotations
  • annotate - Leave annotation

ISA Alignment

According to wanderland-isa, the core should be:

Core Operations

peek(path)                    # Read state
poke(path, value, mode)       # Write state
execute(path, method, args)   # Invoke behavior

Navigation (Keep)

goto <slug>          # Navigate to node
go <direction>       # Navigate directionally
back                 # Previous node
look                 # View current node

Node Management (Keep)

create <slug>        # Create node
edit <slug>          # Edit node
delete <slug>        # Delete node
list                 # List nodes
search <query>       # Search nodes

Links (Keep)

link <node> <direction> <target>    # Create link
edges [slug]                        # View edges

Proposed Cleanup

Phase 1: Consolidate Tag Commands → peek/poke

# REMOVE: tag, add-tag, tags, untag, remove-tag, retag, find-tag, list-tags

# USE INSTEAD:
oculus peek <slug> tags                    # Get tags
oculus poke <slug> tags --add foo          # Add tag
oculus poke <slug> tags --remove bar       # Remove tag
oculus poke <slug> tags --set foo,bar,baz  # Replace all tags
oculus search "tags:foo"                   # Find by tag (enhance search)

Phase 2: Consolidate Metadata → peek/poke

# REMOVE: metadata get/set/edit

# USE INSTEAD:
oculus peek <slug> metadata.author
oculus poke <slug> metadata.author "Alice"

Phase 3: Keep Versioning But Simplify

# KEEP: versions, version, diff, rollback
# These are legitimate operations on version history
# But could potentially be:
oculus peek <slug> history
oculus peek <slug> history.5
oculus execute <slug> rollback --version 5

Phase 4: Fence Operations via Execute

# CURRENT: oculus fence exec <slug> <index> <action>
# BETTER: oculus execute <slug>:<section>:<fence-index> <action> <params>

# Example:
oculus execute daily-tasks:TODO:0 add --content "New task"
oculus execute daily-tasks:TODO:0 check --item 1

Phase 5: Remove/Consolidate Specialized Commands

Remove entirely:

  • code → use oculus peek <slug> code-blocks or fence operations
  • headers → use oculus peek <slug> headers or oculus tree
  • trail → rarely used, can remove
  • annotate/annotations → use fence execute on annotation fences

Keep as-is (useful utilities):

  • tree - structural view
  • path - get file path
  • search - fuzzy search
  • git - git integration
  • aliases - alias management

Success Criteria

  • Reduce commands from 45+ to ~20
  • Align with ISA: peek/poke/execute as primary interface
  • Maintain backwards compatibility via deprecation warnings
  • Improve discoverability through consistent patterns
  • Reduce file size by extracting helpers to modules

Migration Path

  • Add new peek/poke interfaces
  • Mark old commands as deprecated with warnings
  • Update documentation
  • Remove deprecated commands in v2.0

File Organization

Split single 3226-line file into modules:

oculus/
  cli/
    __init__.py          # Main CLI group
    navigation.py        # goto, go, back, look
    nodes.py             # create, edit, delete, list
    graph.py             # peek, poke, execute
    links.py             # link, edges, aliases
    search.py            # search, find
    versioning.py        # versions, diff, rollback
    fence.py             # fence operations
    utils.py             # path, tree, status, git