diff --git a/.gitignore b/.gitignore index 98644fc4..c437e1c1 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ apps/desktop/dist-electron *.tsbuildinfo .DS_Store local/ +local-tools/ .slim/deepwork/ docs !website/docs @@ -17,3 +18,4 @@ MERGE_NOTES.md NEW_FILES.txt PULL_REQUEST.md README_OUR_CHANGES.md +.gitnexus diff --git a/FEATURE_REGISTRY.md b/FEATURE_REGISTRY.md index da0a2b73..07a2a149 100644 --- a/FEATURE_REGISTRY.md +++ b/FEATURE_REGISTRY.md @@ -27,6 +27,7 @@ This is the canonical feature registry for the FamiliarOS working repo. It maps | FamiliarOS rebrand | **merged** | `feat/familiaros-rebrand` | current | repo-wide | App identity, package scopes, plugin IDs, state filenames, preload names, and user-facing strings updated from OpenPets to FamiliarOS. | | Custom Familiar name | **merged** | `feat/familiaros-rebrand` | current | `apps/desktop/src/app-state.ts`, `apps/desktop/src/tray.ts`, `apps/desktop/src/renderer/src/main.tsx` | User-defined name for the default Familiar appears in tray tooltip and context menu. | | Curated familiar catalog safety | **merged** | `feat/familiaros-rebrand` | current | `apps/desktop/src/catalog.ts`, `apps/desktop/src/catalog-validation.ts`, `apps/desktop/catalog.v2.fixture.json`, `apps/desktop/contracts/catalog-fixture.contract.ts` | Curated catalog metadata now preserves `original` / `featured` / category fields end-to-end, uses IP-safer FamiliarOS fixture familiars, and keeps surfaceable pagination totals aligned with the real searchable set. | +| Control Center bridge hardening | **merged** | `feat/familiaros-rebrand` | current | `apps/desktop/src/renderer/src/main.tsx`, `apps/desktop/tests/plugin-ui-static.test.ts` | The Control Center API bridge now resolves to a required `ControlCenterApi` once at startup instead of leaking optionality through the whole renderer, and the static validation was updated to the stricter bridge shape. | ## 2. Floating chat / prompt window diff --git a/apps/desktop/src/renderer/src/main.tsx b/apps/desktop/src/renderer/src/main.tsx index a774ce2e..d0869c58 100644 --- a/apps/desktop/src/renderer/src/main.tsx +++ b/apps/desktop/src/renderer/src/main.tsx @@ -209,10 +209,17 @@ const apiBridge = window as unknown as { openPetsControlCenter?: ControlCenterApi; }; -const api = apiBridge.familiarOSControlCenter ?? apiBridge.openPetsControlCenter; +const api = resolveControlCenterApi(apiBridge); -if (!api) { - throw new Error("FamiliarOS Control Center bridge is unavailable."); +function resolveControlCenterApi(bridge: { + familiarOSControlCenter?: ControlCenterApi; + openPetsControlCenter?: ControlCenterApi; +}): ControlCenterApi { + const resolved = bridge.familiarOSControlCenter ?? bridge.openPetsControlCenter; + if (!resolved) { + throw new Error("FamiliarOS Control Center bridge is unavailable."); + } + return resolved; } const openApiEndpointPresets: readonly OpenApiEndpointPreset[] = [ diff --git a/apps/desktop/tests/plugin-ui-static.test.ts b/apps/desktop/tests/plugin-ui-static.test.ts index cceed816..0252bb73 100644 --- a/apps/desktop/tests/plugin-ui-static.test.ts +++ b/apps/desktop/tests/plugin-ui-static.test.ts @@ -45,7 +45,9 @@ assert.doesNotMatch(controlCenterRendererSource, /OnboardingView|currentRoute == assert.match(controlCenterRendererSource, /materializeListItemDefaults/); assert.match(controlCenterRendererSource, /updateCatalogEntry[\s\S]*api\.updateCatalogPlugin/); assert.match(controlCenterRendererSource, /installed\.source === "catalog"[\s\S]*updateCatalogEntry/); -assert.match(controlCenterRendererSource, /familiarOSControlCenter \?\? apiBridge\.openPetsControlCenter/); +assert.match(controlCenterRendererSource, /const api = resolveControlCenterApi\(apiBridge\);/); +assert.match(controlCenterRendererSource, /function resolveControlCenterApi\(/); +assert.match(controlCenterRendererSource, /bridge\.familiarOSControlCenter \?\? bridge\.openPetsControlCenter/); assert.match(jsHostSource, /FamiliarOSPlugin[\s\S]*register/); assert.match(jsHostSource, /start\(sdk\)/); diff --git a/docs/ops/FAMILIAROS_GITNEXUS_AND_SENTRUX_REFACTORING_BASELINE_2026-06-18.md b/docs/ops/FAMILIAROS_GITNEXUS_AND_SENTRUX_REFACTORING_BASELINE_2026-06-18.md index 9d183f63..e3015772 100644 --- a/docs/ops/FAMILIAROS_GITNEXUS_AND_SENTRUX_REFACTORING_BASELINE_2026-06-18.md +++ b/docs/ops/FAMILIAROS_GITNEXUS_AND_SENTRUX_REFACTORING_BASELINE_2026-06-18.md @@ -4,8 +4,9 @@ ## Purpose -Record the safe FamiliarOS interpretation of the Scriptorium-root GitNexus and -Sentrux surfaces requested for codebase refactoring and hardening work. +Record the safe FamiliarOS interpretation of the Scriptorium-root analyzer +surfaces and the actual 2026-06-18 GitNexus local-tool adoption path used for +FamiliarOS refactoring work. ## Verified Surfaces @@ -15,7 +16,9 @@ Inside `/home/dev/src/ScriptoriumAI`, the relevant root-level analyzer surfaces - `.sentrux/rules.toml` - `sentrux.exe` -These are distinct from the donor/runtime-oriented `mirrors/GitNexus` repo. +These are distinct from the actual GitNexus tool repo under: + +- `/home/dev/src/ScriptoriumAI/mirrors/GitNexus` ## GitNexus Interpretation Rule @@ -30,6 +33,30 @@ Safe FamiliarOS rule: 2. do not trust donor `meta.json` or donor graph blobs as current FamiliarOS truth 3. regenerate FamiliarOS-specific GitNexus state from the repaired high-load workflow when deeper graph analysis is needed +## Actual GitNexus Tool Adoption + +The tool repo used for FamiliarOS was **not** the donor `.gitnexus` index. + +Instead, this pass cloned the actual GitNexus repo from: + +- `/home/dev/src/ScriptoriumAI/mirrors/GitNexus` + +into the FamiliarOS-local tool lane: + +- `/home/dev/src/FamiliarOS/local-tools/GitNexus` + +Important implementation notes: + +- the local clone used the Scriptorium mirror `main` branch, which includes the + indexed-guidance refresh on top of upstream +- the stack-overflow hardening already exists in the adopted tool history at + commit `9eeb20b` (`replace Array.push(...spread) with loop to prevent stack overflow`) +- copied `node_modules` from the donor working tree were **not** safe to reuse + because the local GitNexus run initially failed with `invalid ELF header` + from `@ladybugdb/core` +- the correct recovery was to rebuild the local FamiliarOS clone with native + Linux dependencies instead of trusting donor binary artifacts + ## Sentrux Interpretation Rule The useful transferable part of the root Scriptorium Sentrux surface is the @@ -41,12 +68,48 @@ ruleset that reflects the monorepo's real layers and boundaries. ## FamiliarOS Operating Pattern 1. establish or refresh the FamiliarOS-specific `.sentrux` baseline -2. use repo-local `.gitnexus/` as scaffold only -3. regenerate a true FamiliarOS GitNexus index before large graph-backed refactor work -4. treat GitNexus conclusions as analysis support, not as first-party runtime dependency +2. keep `/home/dev/src/FamiliarOS/local-tools/GitNexus` as the local GitNexus + tool surface +3. use repo-local `.gitnexus/` inside FamiliarOS as generated index state, not + as the tool itself +4. regenerate a true FamiliarOS GitNexus index before large graph-backed + refactor work +5. treat GitNexus conclusions as analysis support, not as first-party runtime + dependency + +## Current FamiliarOS Index Result + +The 2026-06-18 local GitNexus analyze run against `/home/dev/src/FamiliarOS` +completed successfully and produced: + +- `10,383` nodes +- `26,845` edges +- `732` clusters +- `300` flows + +Status check after indexing: + +- repository: `FamiliarOS` +- indexed commit: `edfad05` +- current commit at time of status check: `edfad05` +- state: `up-to-date` + +The resulting FamiliarOS-local generated index now lives in: + +- `/home/dev/src/FamiliarOS/.gitnexus/` ## Current Conclusion -This pass imported the **workflow and scaffold posture** from the Scriptorium -project root while explicitly rejecting the unsafe shortcut of treating the -donor `.gitnexus` payload itself as current FamiliarOS analysis truth. +This pass moved FamiliarOS from "tooling posture only" to a real local analyzer +lane: + +- Sentrux is now represented by a FamiliarOS-specific rules file +- GitNexus now exists as a FamiliarOS-local tool clone +- the FamiliarOS repo has been indexed with native local binaries +- the donor `.gitnexus` payload is still rejected as current truth +- the correct GitNexus interpretation is now operational rather than merely + advisory + +For the FamiliarOS-branded GitNexus refactor procedure, read: + +- `docs/ops/FAMILIAROS_GITNEXUS_REFACTORING_WORKFLOW_2026-06-18.md` diff --git a/docs/ops/FAMILIAROS_GITNEXUS_REFACTORING_WORKFLOW_2026-06-18.md b/docs/ops/FAMILIAROS_GITNEXUS_REFACTORING_WORKFLOW_2026-06-18.md new file mode 100644 index 00000000..0fc3c287 --- /dev/null +++ b/docs/ops/FAMILIAROS_GITNEXUS_REFACTORING_WORKFLOW_2026-06-18.md @@ -0,0 +1,120 @@ +# FamiliarOS GitNexus Refactoring Workflow + +**Date:** 2026-06-18 + +## Purpose + +Translate the GitNexus refactoring skill into a FamiliarOS-owned operating +workflow for safe renames, extractions, splits, and renderer/runtime cleanup. + +This is not a copy-paste donor skill file. It is the FamiliarOS refactor lane +that uses the local GitNexus tool surface and the current FamiliarOS index. + +## Local Tool Surface + +Current local tool path: + +- `/home/dev/src/FamiliarOS/local-tools/GitNexus` + +Current indexed repo name: + +- `FamiliarOS` + +When multiple repos are in the GitNexus registry, always pass: + +- `-r FamiliarOS` + +Otherwise the CLI may resolve against the wrong indexed repo. + +## When To Use GitNexus In FamiliarOS + +Use GitNexus when the task involves: + +- renaming a symbol safely across multiple files +- extracting code from the giant Control Center renderer +- splitting a service or route into smaller modules +- checking blast radius before touching shared desktop/package surfaces +- confirming whether a refactor is isolated or cross-lane + +## FamiliarOS Refactor Sequence + +1. identify the target symbol or concept +2. run `query` to find the relevant flow or file cluster +3. run `context` on the target symbol to inspect incoming and outgoing refs +4. run `impact` before editing to estimate blast radius +5. make the bounded code change +6. rerun FamiliarOS validation for the affected lane +7. if the change is substantial, rerun `analyze` so the FamiliarOS index is fresh again + +## Core Commands + +From `/home/dev/src/FamiliarOS`: + +```bash +node local-tools/GitNexus/gitnexus/dist/cli/index.js status +node local-tools/GitNexus/gitnexus/dist/cli/index.js analyze /home/dev/src/FamiliarOS --skip-agents-md +node local-tools/GitNexus/gitnexus/dist/cli/index.js query -r FamiliarOS "control center bridge" +node local-tools/GitNexus/gitnexus/dist/cli/index.js context -r FamiliarOS -f apps/desktop/src/renderer/src/main.tsx resolveControlCenterApi +node local-tools/GitNexus/gitnexus/dist/cli/index.js impact -r FamiliarOS --depth 2 resolveControlCenterApi +``` + +## FamiliarOS-Specific Risk Rules + +### Low-risk + +- a helper extraction that remains file-local +- a type-hardening fix that removes false optionality +- a renderer-only structural cleanup with no IPC contract change + +### Medium-risk + +- a rename across renderer, preload, and main-process boundaries +- a refactor that changes plugin/runtime interfaces +- changes touching package contracts consumed by multiple surfaces + +### High-risk + +- edits to IPC route names or payload shape +- changes to plugin manifest/runtime contracts +- changes to MCP server tool names, structured content, or CLI surface +- changes to state-file migration or familiar installation layout + +## Applied Example: Control Center Bridge Hardening + +This packet used GitNexus on the Control Center renderer bridge area after the +local FamiliarOS index was built. + +Observed result: + +- `resolveControlCenterApi` was found in + `apps/desktop/src/renderer/src/main.tsx` +- upstream impact came back as `LOW` +- the change stayed isolated to the renderer file plus the static test that + asserted the old bridge shape + +That made the fix an appropriate bounded refactor: + +- resolve the bridge once +- return a required `ControlCenterApi` +- update the static assertion to the new stricter bridge pattern +- rerun desktop `check` + +## What Not To Do + +- do not treat the donor `.gitnexus/meta.json` as if it were the tool +- do not run multi-repo GitNexus commands without `-r FamiliarOS` once multiple + repos are indexed +- do not trust copied native `node_modules` binaries from another working tree +- do not treat GitNexus output as a replacement for tests + +## Validation Rule + +GitNexus is the graph and blast-radius assistant. + +FamiliarOS tests and package checks remain the truth gate after the edit. + +For desktop renderer/control-center work, the default closeout command is: + +```bash +pnpm --filter @familiaros/desktop check +```