Refactor: Launch‑gated global CLI/daemon appliance (strict JSON launch, project attach, docs) #61
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| { | ||
| "$schema": "./project.schema.json", | ||
| "projectId": "codex-synaptic", | ||
| "launchGate": { | ||
| "required": true, | ||
| "strictJsonCommand": "codex-synaptic launch --strict --json" | ||
| }, | ||
| "daemon": { | ||
| "stateDir": "~/.codex-synaptic", | ||
| "allowStateInsideRepo": false | ||
| }, | ||
| "optionalEngines": { | ||
| "ruflo": true, | ||
| "ruvFann": true | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,33 @@ | ||||||
| { | ||||||
| "$schema": "https://json-schema.org/draft/2020-12/schema", | ||||||
| "type": "object", | ||||||
| "required": ["projectId", "launchGate", "daemon"], | ||||||
| "properties": { | ||||||
| "projectId": { "type": "string", "minLength": 1 }, | ||||||
| "launchGate": { | ||||||
| "type": "object", | ||||||
| "required": ["required", "strictJsonCommand"], | ||||||
| "properties": { | ||||||
| "required": { "type": "boolean" }, | ||||||
| "strictJsonCommand": { "type": "string" } | ||||||
| } | ||||||
| }, | ||||||
| "daemon": { | ||||||
| "type": "object", | ||||||
| "required": ["stateDir", "allowStateInsideRepo"], | ||||||
| "properties": { | ||||||
| "stateDir": { "type": "string" }, | ||||||
| "allowStateInsideRepo": { "type": "boolean" } | ||||||
| } | ||||||
| }, | ||||||
| "optionalEngines": { | ||||||
| "type": "object", | ||||||
| "properties": { | ||||||
| "ruflo": { "type": "boolean" }, | ||||||
| "ruvFann": { "type": "boolean" } | ||||||
|
Contributor
There was a problem hiding this comment. To align with the suggested change of standardizing the optional engine name to
Suggested change
|
||||||
| }, | ||||||
| "additionalProperties": false | ||||||
| } | ||||||
| }, | ||||||
| "additionalProperties": false | ||||||
| } | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| [project] | ||
| root = "." | ||
| trusted = true | ||
| sandbox = "workspace-write" | ||
| approvals = "on-request" | ||
|
|
||
| [paths] | ||
| restrict_to_project_root = true | ||
|
|
||
| [mcp_servers.filesystem] | ||
| command = "npx" | ||
| args = ["-y", "@modelcontextprotocol/server-filesystem", "."] | ||
|
|
||
| [mcp_servers.playwright] | ||
| command = "npx" | ||
| args = ["-y", "@playwright/mcp@latest"] | ||
|
|
||
| [mcp_servers.desktop_commander] | ||
| command = "npx" | ||
| args = ["-y", "@modelcontextprotocol/server-desktop-commander"] | ||
|
Comment on lines
+14
to
+20
Contributor
There was a problem hiding this comment. 🧩 Analysis chain🌐 Web query:
💡 Result: The latest published version of 🌐 Web query:
💡 Result: The latest stable version published for the There are also newer pre-release (alpha) builds under the Sources: [1] [2] 🌐 Web query:
💡 Result: I couldn’t verify any published version for In practice, “Desktop Commander” is commonly installed/run as Sources: Citations:
🏁 Script executed: cat .codex/config.tomlRepository: clduab11/codex-synaptic Length of output: 495 Verify the The config references a package that cannot be resolved. Consider checking if you meant Separately, consider pinning MCP server versions for reproducibility. Currently,
Without pinning, each 🤖 Prompt for AI Agents |
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,156 +1,58 @@ | ||
| # codex-synaptic | ||
|
|
||
| Codex-Synaptic is an **appliance-grade global CLI + daemon** for Codex on macOS. Install once, attach to any repository, run a deterministic launch gate, and only then execute bounded workflows. | ||
|
|
||
| ## Product model | ||
|
|
||
| - **Codex is the cockpit**: app threads, VS Code extension, automations, approvals, and worktrees. | ||
| - **Synaptic is the engine room**: daemon lifecycle, readiness checks, MCP routing, telemetry, and release hygiene. | ||
| - **Launch Gate is the contract**: `codex-synaptic launch --strict --json` is the first command for every workflow. | ||
| - **Optional engines**: | ||
| - `ruflo` adapter (optional, capability upgrade only) | ||
| - `ruv-FANN` adapter (optional, capability upgrade only) | ||
|
|
||
| ## 5-minute first run | ||
|
|
||
| ```bash | ||
| # 1) Install globally | ||
| npm install -g codex-synaptic | ||
|
|
||
| # 2) Verify global CLI | ||
| codex-synaptic --help | ||
|
|
||
| # 3) Attach current repository | ||
| codex-synaptic project attach . | ||
|
|
||
| # 4) Run deterministic launch gate | ||
| codex-synaptic launch --strict --json | ||
|
|
||
| # 5) Apply safe remediations (from fixes[].safeUnderSandbox=true), rerun launch | ||
| codex-synaptic launch --strict --json | ||
| ``` | ||
|
|
||
| When `ok=true`, start your bounded workflow and produce a report artifact (diff summary, validation log, and follow-up backlog). | ||
|
|
||
| ## Attach a new repository | ||
|
|
||
| ```bash | ||
| cd /path/to/target-repo | ||
| codex-synaptic project attach . | ||
| codex-synaptic launch --strict --json | ||
| ``` | ||
|
|
||
| Synaptic discovers and uses: | ||
|
|
||
| - `AGENTS.md` for Codex instructions | ||
| - `.codex/config.toml` for Codex project config and MCP | ||
| - `.codex-synaptic/project.json` for Synaptic project-local behavior (optional) | ||
|
|
||
| ## Worktree + sandbox safety | ||
|
|
||
| - Daemon state is global and **outside** repository/worktree paths (default: `~/.codex-synaptic`). | ||
| - Preferred sandbox for development and launch remediations: `workspace-write`. | ||
| - Launch report explicitly marks unsafe remediations with `safeUnderSandbox=false` and indicates minimal extra allowlist needs. | ||
|
|
||
| See: | ||
| - `docs/launch-gate.md` | ||
| - `docs/codex-usage.md` | ||
| - `docs/sandbox-and-rules.md` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| # Codex usage (macOS app, threads, automations, VS Code) | ||
|
|
||
| ## Launch-first workflow | ||
|
|
||
| 1. Open repository in Codex for macOS or Codex VS Code extension. | ||
| 2. Run `codex-synaptic launch --strict --json`. | ||
| 3. Apply safe fixes from `fixes[]`. | ||
| 4. Re-run launch until `ok=true`. | ||
| 5. Execute bounded workflow and publish a report artifact. | ||
|
|
||
| ## Daily automation template | ||
|
|
||
| **Name:** Daily Launch Gate + Brief Report | ||
|
|
||
| ```bash | ||
| codex-synaptic launch --strict --json > .codex-synaptic/reports/daily-launch.json | ||
| npm run build > .codex-synaptic/reports/daily-build.log 2>&1 | ||
| npm run test > .codex-synaptic/reports/daily-test.log 2>&1 | ||
| ``` | ||
|
|
||
| Output artifact: `.codex-synaptic/reports/daily-launch.json` + logs, committed or attached to thread. | ||
|
|
||
| ## Nightly automation template | ||
|
|
||
| **Name:** Nightly Docs Drift / Friction Scan | ||
|
|
||
| ```bash | ||
| codex-synaptic launch --strict --json > .codex-synaptic/reports/nightly-launch.json | ||
| git diff -- README.md AGENTS.md docs/ > .codex-synaptic/reports/nightly-docs-drift.diff || true | ||
| ``` | ||
|
|
||
| Output artifact: diff-ready drift report for next working day triage. | ||
|
|
||
| ## Weekly automation template | ||
|
|
||
| **Name:** Weekly Release Preflight | ||
|
|
||
| ```bash | ||
| codex-synaptic launch --strict --json > .codex-synaptic/reports/weekly-launch.json | ||
| npm run build > .codex-synaptic/reports/weekly-build.log 2>&1 | ||
| npm run test > .codex-synaptic/reports/weekly-test.log 2>&1 | ||
| ``` | ||
|
|
||
| Output artifact: preflight bundle for release thread/PR checklist. | ||
|
|
||
| ## Worktree behavior | ||
|
|
||
| - Run automations in dedicated worktrees. | ||
| - Keep artifacts in project-local `.codex-synaptic/reports/`. | ||
| - Keep daemon runtime/state outside worktrees (`~/.codex-synaptic` by default). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| # Launch Gate | ||
|
|
||
| `codex-synaptic launch --strict --json` is the deterministic readiness contract for this appliance. | ||
|
|
||
| ## Strict JSON schema | ||
|
|
||
| ```json | ||
| { | ||
| "ok": true, | ||
| "capabilities": ["..."], | ||
| "checks": [ | ||
| { "name": "...", "status": "pass|fail|warn", "detail": "..." } | ||
| ], | ||
| "fixes": [ | ||
| { "why": "...", "command": "...", "safeUnderSandbox": true } | ||
| ], | ||
| "nextActions": ["..."] | ||
| } | ||
| ``` | ||
|
|
||
| ## Required checks | ||
|
|
||
| The gate emits at least: | ||
| - `runtime.node` | ||
| - `runtime.npm` | ||
| - `repo.dependencies` | ||
| - `repo.build` | ||
| - `repo.typecheck` | ||
| - `repo.test` | ||
| - `daemon.health` | ||
| - `mcp.config` | ||
| - `worktree.state_location` | ||
| - optional capability checks (`optional.ruflo`, `optional.ruv-fann`) as non-blocking warnings | ||
|
|
||
| ## Remediation semantics | ||
|
|
||
| - `safeUnderSandbox=true` means the fix is expected to run under workspace-write. | ||
| - `safeUnderSandbox=false` means the fix needs additional host allowlist or elevated rules. | ||
| - Apply safe fixes first, rerun launch, and only then proceed to workflow execution. | ||
|
|
||
| ## Failure handling contract | ||
|
|
||
| - In strict mode, the command exits non-zero when `ok=false`. | ||
| - Optional engines can downgrade capabilities but must not fail core boot. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| # Sandbox and rules | ||
|
|
||
| ## Default mode | ||
|
|
||
| Use workspace-write by default: | ||
|
|
||
| ```bash | ||
| codex --sandbox workspace-write --ask-for-approval on-request | ||
| ``` | ||
|
|
||
| ## Safe command set | ||
|
|
||
| Safe under workspace-write for this repo: | ||
| - `codex-synaptic launch --strict --json` | ||
| - `codex-synaptic project attach <path>` | ||
| - `codex-synaptic background status|start|attach|logs|stop` | ||
| - `npm install` | ||
| - `npm run build` | ||
| - `npm run test` | ||
| - `npm exec tsc -- --noEmit` | ||
|
|
||
| ## Commands that need extra allowlist | ||
|
|
||
| Mark as unsafe (`safeUnderSandbox=false`) and request minimal allowlist: | ||
| - `brew install ...` | ||
| - `npm install -g ...` | ||
| - Docker auth operations (`codex-synaptic env docker-login ...`) | ||
| - Any command requiring writes outside workspace scope | ||
|
|
||
| ## Minimal approval guidance | ||
|
|
||
| When a command is unsafe, specify: | ||
| 1. exact command | ||
| 2. reason it needs elevated scope | ||
| 3. smallest file/path/network allowance needed | ||
|
|
||
| Never require blanket full-access defaults. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's an inconsistency in the naming of the optional engine. Here it's
ruvFann(camelCase), but the implementation insrc/adapters/optional-engines.tsandsrc/cli/launch.tsexpectsruv-fann(kebab-case). The documentation also usesruv-FANNorruv-fann. This discrepancy will prevent the configuration from being correctly applied.To ensure consistency and correct functionality, I recommend standardizing on
ruv-fannacross all configuration, code, and documentation. This is also a more common convention for keys representing tool names in configuration files.