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 paths and effective non-secret values needed for local routing. It should not dump bearer tokens, auth headers, raw project config contents, 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.

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 builds the local CLI and runs the built artifact:

pnpm --dir "$SITEOS_DEV_SHELL_CLI_ROOT" build
node "$SITEOS_DEV_SHELL_CLI_ROOT/dist/cli.js" ...

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:

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 creates a 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.

Intercepted npx @s-os/cli ... calls fail when the local CLI build fails or when dist/cli.js is missing after build. 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"