SiteOS Dev Shell

@s-os/dev_shell provides the siteos_dev_shell command for local SiteOS CLI development.

Use it when a developer, coding agent, unit smoke, or eval should exercise local @s-os/cli changes through the same public command shape that external projects use:

npx @s-os/cli health-check

The dev shell prepares a process environment that routes selected SiteOS CLI package calls to the configured local repository checkout. Target projects remain untouched.

Safety Boundaries

siteos_dev_shell does not edit target project package files, create symlinks, run dependency installs in the target project, or change public SiteOS skills. Public skills should keep using normal public commands such as npx @s-os/cli ...; they do not need to know whether a local dev shell is active.

The dev shell reports the non-secret routing values needed for local development. It should not dump bearer tokens, auth headers, or other secret-bearing values.

Configuration

siteos_dev_shell resolves configuration before launching a shell or script:

1. Walk upward from the launch cwd looking for .siteos/dev-harness.json.
2. If no project-local config exists, fall back to ~/.siteos/dev-harness.json.
3. If neither exists, fail with a clear error.

Example .siteos/dev-harness.json:

{
  "version": 1,
  "siteosRepoRoot": "..",
  "cliPackagePath": "packages/cli",
  "apiBaseUrl": "http://localhost:3020",
  "siteosHome": "dev-shell/siteos-home"
}

Path resolution:

• siteosRepoRoot is resolved relative to the directory containing dev-harness.json.
• cliPackagePath is resolved relative to siteosRepoRoot.
• siteosHome is resolved relative to the directory containing dev-harness.json.

The resolved cliPackagePath must contain package.json for @s-os/cli.

Usage

Show usage:

siteos_dev_shell --help

Start an interactive shell from the current directory:

siteos_dev_shell

Start an interactive shell in a specific project directory:

siteos_dev_shell --dir /path/to/project

--dir selects the spawned shell or script cwd. Config lookup still starts from the original launch cwd.

Run a command and exit with that command's status:

siteos_dev_shell --dir /path/to/project --script "npx @s-os/cli health-check"

--script runs through bash -lc, preserves the dev-shell PATH, does not print the interactive banner, and exits with the command status.

Run a command, report its non-zero exit if it fails, then stay in an interactive shell:

siteos_dev_shell --dir /path/to/project --script-interactive "npx @s-os/cli health-check"

--script-interactive uses the same script execution path first, then opens the configured interactive shell in the same cwd and environment.

Environment

Child processes receive:

• SITEOS_DEV_SHELL_REAL_NPX: the real npx executable captured before the dev-shell shim is prepended to PATH.
• SITEOS_DEV_SHELL_CLI_ROOT: the resolved local @s-os/cli package directory.
• SITEOS_DEV_SHELL_CONFIG_PATH: the selected dev-harness.json path.
• SITEOS_API_BASE_URL: the configured SiteOS API base URL.
• SITEOS_HOME: the configured local CLI home directory.

API Health Diagnostic

Before launching a script or interactive shell, siteos_dev_shell checks:

GET <apiBaseUrl>/api/health

The expected SiteOS server payload is:

{ "ok": true, "service": "siteos-server" }

The diagnostic is informational and does not block the command. A reachable server prints:

SiteOS API: ✅ http://localhost:3020 (/api/health 200)

An unreachable or unhealthy server prints:

SiteOS API: ❌ http://localhost:3020 (/api/health failed: connection refused)

Npx Routing

siteos_dev_shell writes a small runtime launcher at:

<siteosRepoRoot>/.siteos/dev-shell/bin/npx

That directory is prepended to child PATH. The launcher delegates to committed package code and intercepts only these unversioned SiteOS CLI package forms:

npx @s-os/cli health-check
npx --yes @s-os/cli health-check
npx -y @s-os/cli health-check

Every intercepted call runs the local CLI build artifact directly:

node "$SITEOS_DEV_SHELL_CLI_ROOT/dist/cli.js" ...

The shim does not test or build the CLI. Build it once before a manual run, or keep the watch process running in a second terminal while developing:

pnpm --dir packages/cli build
pnpm --dir packages/cli dev:watch

If dist/cli.js is missing, the intercepted command fails with a clear prompt to run build or dev:watch.

Explicit versions and unrelated packages pass through to the captured real npx:

npx @s-os/cli@latest health-check
npx @s-os/[email protected] health-check
npx cowsay hello

Common Workflows

Manually test local CLI changes before publish:

pnpm --dir packages/cli dev:watch
siteos_dev_shell --dir /path/to/sandbox
npx @s-os/cli health-check

Run one smoke command from automation:

siteos_dev_shell --dir /path/to/sandbox --script "npx @s-os/cli health-check"

Launch a coding agent so normal public commands route to the local CLI:

siteos_dev_shell --dir /path/to/sandbox --script-interactive "codex --yolo"

Run eval or unit smoke commands with deterministic routing:

siteos_dev_shell --dir /path/to/sandbox --script "pnpm test"

Repository Verification

From the repository root, run the maintained external-sandbox contour:

pnpm verify:dev-shell

The check builds and tests the CLI and dev-shell packages, creates an isolated temp project, verifies direct and dev-shell-routed health-check, proves unrelated npx pass-through with a fake real npx, checks --script-interactive with a fake shell, and confirms the target project file list is unchanged.

Before publish, run the packed-package contour:

pnpm verify:dev-shell:pack

The packed check builds the CLI, creates a dev-shell package tarball, installs it into a fresh temp consumer project, runs the installed siteos_dev_shell bin, verifies routed local CLI execution and unrelated npx pass-through, checks --script-interactive with a fake shell, and confirms the target project remains free of package, dependency, symlink, and wrapper artifacts.

Failure Behavior

The command fails before spawning child work when configuration is missing or invalid, the real npx cannot be found, or the configured CLI package cannot be resolved.

The API health diagnostic never determines the command exit status. It is a startup warning so a developer can immediately see when apiBaseUrl is unreachable or malformed before an agent run starts depending on that server. It waits up to 1.5 seconds for an unreachable server before continuing.

Intercepted npx @s-os/cli ... calls fail when dist/cli.js is missing or when the built CLI exits non-zero. Unrecognized npx command shapes pass through to the real npx instead of being partially intercepted.

Safe troubleshooting checks:

siteos_dev_shell --help
siteos_dev_shell --dir /path/to/project --script "pwd"
siteos_dev_shell --dir /path/to/project --script "node -e 'console.log(process.env.SITEOS_DEV_SHELL_CLI_ROOT)'"
siteos_dev_shell --dir /path/to/project --script "npx @s-os/cli health-check"