> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_38/session_02_platform_foundation.md). # Session 02: Platform Foundation **Session ID**: `phase38-session02-platform-foundation` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours *** ## Objective Establish one shared cross-platform helper layer for paths, app-data locations, CLI lookup, and virtual-environment binary layout. *** ## Non-Negotiable Delivery Bar The helper layer is complete only when real branch behavior is exercised through tests or faithful platform harnesses. A file that exports constants without proving Windows, macOS, and Linux behavior is not enough. *** ## Source Items * 1.1 `ADAPT`: shared platform module. *** ## Scope ### In Scope (MVP) * Create `/home/aiwithapex/projects/aios/scripts/lib/platform.ts` from upstream platform concepts. * Re-export from `/home/aiwithapex/projects/aios/scripts/platform.ts` only if a root-level import path is needed. * Centralize helpers for `IS_WIN`, `IS_MACOS`, path normalization via `toPosix()`, app-data paths, CLI lookup candidates, and venv binary paths. * Reconcile duplicate platform branches currently in `/home/aiwithapex/projects/aios/scripts/lib/scan-helpers.ts` and `/home/aiwithapex/projects/aios/scripts/lib/tool-detection.ts`. * Add tests for mocked `win32`, `darwin`, and `linux` branch behavior. ### Out of Scope * Behavior changes beyond centralizing existing platform logic. * Windows aggregate behavior. * Dream scheduling. * Request-time bridge hardening. * Voice broker and Intelligence portal. *** ## Detailed Port Item ### 1.1 Shared Platform Module Upstream introduced `scripts/platform.ts` with about 70 lines exporting Windows and macOS flags, `toPosix()`, app-data paths, CLI lookup, and venv bin paths. Every later Windows change depends on it. * Upstream source: `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/scripts/platform.ts` at patch line 1392. * AI OS target: `/home/aiwithapex/projects/aios/scripts/lib/platform.ts`. * Optional AI OS target: `/home/aiwithapex/projects/aios/scripts/platform.ts` if other root scripts need the upstream import path. * Adaptation: keep AI OS convention by placing shared helpers under `scripts/lib/`, not root `scripts/`, unless compatibility requires a re-export. * Required reconciliation: `/home/aiwithapex/projects/aios/scripts/lib/scan-helpers.ts` and `/home/aiwithapex/projects/aios/scripts/lib/tool-detection.ts` must not retain duplicate platform branch logic that drifts from the new helper. * Risk: low but foundational. A bad abstraction will break Sessions 03 through 05 and runtime bridge behavior. * DoD: each exported helper has a test asserting correct results on Windows and macOS/Linux `process.platform` values. No duplicate source of truth remains in scan helpers or tool detection for the same path/candidate decisions. *** ## Implementation Notes * Prefer dependency-injected platform values or testable helper functions over hard-to-mock reads of `process.platform`. * Keep Windows path handling explicit for drive letters, backslashes, app-data directories, `.cmd` and `.exe` candidates, and venv `Scripts`. * Preserve existing POSIX behavior as the regression baseline. * Do not pull in aggregate, scheduler, setup, or bridge behavior changes merely because those sessions will later consume this module. *** ## Prerequisites * [ ] Session 01 completed or confirmed not to block helper creation. * [ ] Existing scan-helper and tool-detection branch logic is inventoried. * [ ] Current tests for `tool-detection` and scan helpers are identified. *** ## Deliverables 1. `scripts/lib/platform.ts` with shared platform helpers. 2. Optional `scripts/platform.ts` compatibility re-export only if needed. 3. Updated scan and tool-detection helpers using the shared platform module. 4. Unit tests for `toPosix`, app-data paths, CLI candidates, and venv bin paths. *** ## Success Criteria * [ ] Platform helper tests pass for mocked `win32`, `darwin`, and `linux`. * [ ] Existing scan and tool-detection tests still pass. * [ ] There are not two independent sources of platform path truth in touched script helpers. * [ ] Public behavior remains unchanged except for improved internal centralization. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_38/session_02_platform_foundation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.