What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	13531
title	Replace migrateWakeSubscriptions.mjs hand-rolled parseArgs with commander
state	Closed
labels	airefactoring
assignees	neo-opus-grace
createdAt	Jun 19, 2026, 10:07 AM
updatedAt	Jun 20, 2026, 11:45 PM
githubUrl	https://github.com/neomjs/neo/issues/13531
author	neo-opus-grace
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 20, 2026, 11:45 PM

Replace migrateWakeSubscriptions.mjs hand-rolled parseArgs with commander

Closed v13.1.0/archive-v13-1-0-chunk-4 airefactoring

neo-opus-grace commented on Jun 19, 2026, 10:07 AM

Context

Operator-flagged on PR #13511's diff: ai/scripts/migrations/migrateWakeSubscriptions.mjs hand-rolls CLI argument parsing. commander is already the repo convention — a devDependency (^14.0.3) used by ~10 ai/scripts/maintenance/ scripts (purgeTestCollections.mjs, compactGraphLog.mjs, defragChromaDB.mjs, auditGraphIntegrity.mjs, …). This ticket aligns the migration script to that established pattern; it is convention-alignment, not a new dependency.

Live latest-open sweep: checked open issues for commander/parseArgs/CLI-arg refactors at ~2026-06-19T08:05Z; no equivalent. Release classification: boardless (refactor / consistency; post-v13).

The Problem

migrateWakeSubscriptions.mjs hand-rolls a parseArgs(argv) loop + a printUsage() for --apply / --audit / --db <path> / --help, including manual unknown-argument handling. This duplicates — less robustly — what commander provides declaratively (option definitions, value coercion, auto-generated --help, unknown-option errors), and diverges from the maintenance-script convention.

The Fix

Replace parseArgs() + printUsage() with a commander Command:

.option('--apply', ...), .option('--audit', ...), .option('--db <path>', ...), auto --help.
Mirror the existing idiom in a sibling, e.g. ai/scripts/maintenance/purgeTestCollections.mjs.
Keep the main() dispatch + the exported runMigration / auditWakeRoutes / resolveRouteAddress untouched (only the argv → options surface changes).

Avoided Traps / Gold Standards Rejected

Node built-in util.parseArgs (available — engines.node >=24, running v25): rejected. Introducing a second arg-parsing primitive would fragment the convention already standardized on commander. Consistency > minimalism here.

Sequencing / Blocked-by

Blocked-by #13511. That PR modifies this same file (adds --audit / auditWakeRoutes). Land this refactor only after #13511 merges, or it conflicts with the unmerged --audit addition.

Acceptance Criteria

parseArgs() + printUsage() replaced by a commander Command; no hand-rolled argv loop remains.
Behavior preserved: --apply (commit), --audit (read-only audit), --db <path> (override), --help (usage), unknown-arg → error.
Matches the ai/scripts/maintenance/ commander idiom (cite the sibling followed).
migrateWakeSubscriptions.spec.mjs stays green (the spec exercises runMigration / auditWakeRoutes, which are unchanged).

Out of Scope

The other hand-rolled-argv holdouts (runSandman.mjs, runAgent.mjs, several buildScripts/create/*, …) — a broader convention-sweep belongs in its own ticket; this one is the migration script only.

Surfaced in: PR #13511 (Resolves #13510, Refs #13481) — the wake-route disambiguation work that added --audit.

Origin Session ID

045a6048-1e1d-44c1-9738-7f09b62cc998