oculus-cli-cleanup-proposal

Oculus CLI Cleanup Proposal

Executive Summary

Reduce oculus CLI from 45+ commands (3226 lines) to ~15-20 core commands by aligning with the wanderland-isa specification and consolidating redundant functionality.

Core Philosophy

The wanderland-isa defines a 3-operation interface:

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

Everything else should build on these primitives, not create new top-level commands.

Proposed Command Structure

Tier 1: Core ISA Operations (3 commands)

oculus peek <address> [--format json|yaml|raw|text]
oculus poke <address> <value> [--mode set|append|prepend] [--context "..."]
oculus execute <address> <method> [--params json] [--context "..."]

Address format: slug:section:fence-index:path

Examples:

# Read operations
oculus peek daily-tasks config.version
oculus peek daily-tasks metadata.tags
oculus peek daily-tasks TODO:0  # Get todo fence state

# Write operations
oculus poke daily-tasks config.version "2.0.0" --mode set
oculus poke daily-tasks metadata.tags "bug" --mode append
oculus poke daily-tasks prose "New content" --mode append

# Execute operations
oculus execute daily-tasks TODO:0 add --params '{"content":"New task"}'
oculus execute daily-tasks TODO:0 check --params '{"item_index":0}'

Tier 2: Navigation (4 commands)

oculus goto <slug> [--mode raw|interpolated|rendered|executed]
oculus go <direction> [<slot-index>]
oculus back
oculus look

Keep as-is - these are fundamental to the navigation model.

Tier 3: Node Management (5 commands)

oculus create <slug> [options]
oculus edit <slug>
oculus delete <slug> [--hard]
oculus list [--type TYPE] [--source SOURCE] [--plain]
oculus search <query>

Keep as-is - these are CRUD operations on nodes.

Tier 4: Graph Operations (3 commands)

oculus link <node> <direction> <target> [--backlink]
oculus edges [slug]
oculus tree <address> [--depth N] [--mode tree|headers|interactive]

Keep as-is - these are essential graph operations.

Tier 5: Utilities (5-7 commands)

oculus path [slug]           # Get file path
oculus status                # System status
oculus cache {clear|status}  # Cache management
oculus git <slug>            # Git integration
oculus alias <name> <target> # Alias management
oculus aliases               # List aliases

Keep useful utilities that don't fit into ISA model.

Commands to REMOVE or CONSOLIDATE

❌ Remove: Tag Commands (7 → 0)

Current chaos:

oculus tag <slug> <tag>
oculus add-tag <slug> <tag>
oculus tags <slug>
oculus untag <slug> <tag>
oculus remove-tag <slug> <tag>
oculus retag <slug> <tag1> <tag2>
oculus find-tag <tag>
oculus list-tags

Replace with peek/poke:

# Read tags
oculus peek <slug> metadata.tags

# Add tag
oculus poke <slug> metadata.tags "new-tag" --mode append

# Remove tag (requires array manipulation support in poke)
oculus poke <slug> metadata.tags --remove "old-tag"

# Set all tags (replace)
oculus poke <slug> metadata.tags "tag1,tag2,tag3" --mode set

# Find by tag (enhance search)
oculus search "tags:debugging"

# List all tags (new peek on registry)
oculus peek :registry tags

Implementation needed:

Array manipulation in poke (append, remove, set)
Enhanced search with tag filter syntax

❌ Remove: Metadata Commands (3 → 0)

Current:

oculus metadata get <slug>
oculus metadata set <slug> <key>=<value>
oculus metadata edit <slug>

Replace with peek/poke:

# Get metadata
oculus peek <slug> metadata
oculus peek <slug> metadata.author

# Set metadata
oculus poke <slug> metadata.author "Alice" --mode set
oculus poke <slug> metadata.priority "high" --mode set

# Edit (just use regular edit command)
oculus edit <slug>

❌ Consolidate: Fence Commands (3 → 0)

Current:

oculus fence list <slug>
oculus fence view <slug> <index>
oculus fence exec <slug> <index> <action>

Replace with ISA operations:

# List fences (use tree)
oculus tree <slug>

# View fence
oculus peek <slug> TODO:0

# Execute fence action
oculus execute <slug> TODO:0 add --params '{"content":"Task"}'

❌ Consolidate: Version Commands (Keep 2, Remove 3)

Keep:

oculus versions [slug]                    # List versions
oculus rollback <slug> --version N        # Rollback

Remove (can use peek/execute):

oculus history <slug>                     # Use: oculus versions
oculus version <slug> --version N         # Use: oculus peek slug@version:5
oculus diff <slug> --from N --to M        # Use: oculus peek slug diff:N:M

❌ Remove: Specialized Commands (5 commands)

oculus code <slug>              # Use: oculus peek <slug> code-blocks
oculus headers <slug>           # Use: oculus tree <slug> --mode headers
oculus annotate                 # Use fence operations
oculus annotations              # Use fence operations
oculus trail <author>           # Rarely used, remove

❌ Remove: Stuffy Integration (Move to separate CLI)

oculus stuffy-download <channel> <slug>

Why: This is stuffy-specific, not core oculus. Should be stuffy download --to-oculus instead.

File Organization Cleanup

Split oculus/cli.py (3226 lines) into modules:

oculus/
  cli/
    __init__.py              # Main CLI group (50 lines)
    core.py                  # peek, poke, execute (300 lines)
    navigation.py            # goto, go, back, look (200 lines)
    nodes.py                 # create, edit, delete, list, search (400 lines)
    graph.py                 # link, edges, tree (250 lines)
    utils.py                 # path, status, cache, git, aliases (300 lines)
    formatting.py            # display_node, render helpers (400 lines)
    address_parser.py        # parse_address logic (150 lines)

Total: ~2000 lines split across 8 focused files (vs 3226 in one file)

Migration Strategy

Phase 1: Add New Commands (v0.2)

Implement enhanced peek with full path support
Implement enhanced poke with array operations
Implement execute for fence operations
Add deprecation warnings to old commands

Phase 2: Deprecation Period (v0.3-0.5)

All old commands print deprecation warning
Documentation updated to show new syntax
Provide migration guide

Phase 3: Removal (v1.0)

Remove deprecated commands
Clean up code organization
Simplified help output

Enhanced Peek/Poke Capabilities

Peek Enhancements

# Current position
oculus peek metadata.author              # Assumes current node
oculus peek : metadata.author            # Explicit current

# Specific node
oculus peek daily-tasks metadata.tags

# Section within node
oculus peek daily-tasks:Results prose

# Fence within section
oculus peek daily-tasks:Tasks:TODO:0

# Deep path into fence
oculus peek daily-tasks:Config:YAML:0 config.database.host

# Special paths
oculus peek daily-tasks headers          # List all headers
oculus peek daily-tasks code-blocks      # List code fences
oculus peek daily-tasks links            # All links

# Registry queries
oculus peek :registry tags               # All tags
oculus peek :registry nodes.count        # Node count

Poke Enhancements

# Modes
--mode set       # Replace entire value
--mode append    # Add to end
--mode prepend   # Add to beginning

# Array operations (new)
--mode append    # Works for arrays too
--remove <value> # Remove from array (special flag)

# Examples
oculus poke daily-tasks metadata.tags "debug" --mode append
oculus poke daily-tasks metadata.tags --remove "wontfix"
oculus poke daily-tasks:Results prose "## New Section" --mode append
oculus poke daily-tasks:Config:YAML:0 config.timeout 60 --mode set

Execute Enhancements

# Generic syntax
oculus execute <address> <method> --params <json>

# Examples
oculus execute daily-tasks:TODO:0 add --params '{"content":"New task","metadata":{"priority":"high"}}'
oculus execute daily-tasks:TODO:0 check --params '{"item_index":0}'
oculus execute daily-tasks:TODO:0 toggle --params '{"item_index":1}'
oculus execute daily-tasks:CODE:2 run --params '{}'

# Context tracking
oculus execute daily-tasks:TODO:0 add --params '...' --context "User completing sprint tasks"

Benefits

1. Reduced Complexity

45+ commands → ~20 commands (56% reduction)
3226 lines → ~2000 lines (38% reduction)
8 focused modules vs 1 monolithic file

2. ISA Alignment

peek/poke/execute as primary interface
Consistent addressing model
Predictable behavior

3. Improved Discoverability

Fewer commands to remember
Consistent patterns
Clear mental model

4. Better Extensibility

New fence types work automatically
No new commands needed
Just implement fence provider

5. Maintainability

Focused modules
Clear separation of concerns
Easier to test

Risks and Mitigation

Risk: Breaking Changes

Mitigation:

Long deprecation period
Clear migration guide
Backwards compatibility shims

Risk: More Complex Individual Commands

Mitigation:

Good help text
Tab completion
Interactive mode for complex operations

Risk: Learning Curve

Mitigation:

Comprehensive examples
Migration guide
Deprecation warnings show new syntax

Success Metrics

Command count: 45+ → ~20 (target: 50%+ reduction)
File size: 3226 → ~2000 lines (target: 30%+ reduction)
Module count: 1 → 8 focused files
User satisfaction: Survey after v1.0 release
Documentation clarity: Reduced help text, clearer patterns

Next Steps

Review this proposal with team/users
Prototype peek/poke/execute enhancements
Create migration guide for common operations
Implement Phase 1 (new commands + deprecation)
Gather feedback during deprecation period
Execute Phase 3 (removal in v1.0)

Example Migration Guide

Old Syntax	New Syntax
`oculus tags <slug>`	`oculus peek <slug> metadata.tags`
`oculus add-tag <slug> foo`	`oculus poke <slug> metadata.tags "foo" --mode append`
`oculus remove-tag <slug> bar`	`oculus poke <slug> metadata.tags --remove "bar"`
`oculus find-tag debugging`	`oculus search "tags:debugging"`

Metadata

['wanderland', 'oculus', 'terminal-velocity']

Fences

Old Syntax	New Syntax
`oculus fence list <slug>`	`oculus tree <slug>`
`oculus fence view <slug> 0`	`oculus peek <slug> TODO:0`
`oculus fence exec <slug> 0 add --content "X"`	`oculus execute <slug> TODO:0 add --params '{"content":"X"}'`

Appendix: Full Command Comparison

Before (45+ commands)

look, goto, go, back, current, last
edges, list, search, status
create, edit, delete, path
tag, add-tag, tags, untag, remove-tag, retag, find-tag, list-tags
metadata (get, set, edit)
fence (list, view, exec)
peek, poke, execute
link, aliases, alias, unalias
tree, code, headers
versions, version, history, diff, rollback
git, cache
annotate, annotations, delete-annotation
trail, stuffy-download
rename, links

After (~20 commands)

Core: peek, poke, execute
Navigation: look, goto, go, back
Nodes: create, edit, delete, list, search
Graph: link, edges, tree
Utils: path, status, cache, git, alias, aliases

Removed via Consolidation

All tag commands → peek/poke
All metadata commands → peek/poke
All fence commands → peek/poke/execute
code, headers → peek/tree
version, history, diff → peek (keep versions, rollback)
annotations, trail → rarely used
stuffy-download → move to stuffy CLI

Oculus CLI Cleanup Proposal

Executive Summary

Core Philosophy

Proposed Command Structure

Tier 1: Core ISA Operations (3 commands)

Tier 2: Navigation (4 commands)

Tier 3: Node Management (5 commands)

Tier 4: Graph Operations (3 commands)

Tier 5: Utilities (5-7 commands)

Commands to REMOVE or CONSOLIDATE

❌ Remove: Tag Commands (7 → 0)

❌ Remove: Metadata Commands (3 → 0)

❌ Consolidate: Fence Commands (3 → 0)

❌ Consolidate: Version Commands (Keep 2, Remove 3)

❌ Remove: Specialized Commands (5 commands)

❌ Remove: Stuffy Integration (Move to separate CLI)

File Organization Cleanup

Migration Strategy

Phase 1: Add New Commands (v0.2)

Phase 2: Deprecation Period (v0.3-0.5)

Phase 3: Removal (v1.0)

Enhanced Peek/Poke Capabilities

Peek Enhancements

Poke Enhancements

Execute Enhancements

Benefits

1. Reduced Complexity

2. ISA Alignment

3. Improved Discoverability

4. Better Extensibility

5. Maintainability

Risks and Mitigation

Risk: Breaking Changes

Risk: More Complex Individual Commands

Risk: Learning Curve

Success Metrics

Next Steps

Example Migration Guide

Tags

Metadata

Fences

Appendix: Full Command Comparison

Before (45+ commands)

After (~20 commands)

Removed via Consolidation