Cameek.Run67.Tool 0.0.10

Cameek.Run67

Cameek.Run67 is a human-first execution runtime for reusable operational flows, designed for composition, explicit planning, safe expressions, persistent state, and multiple hosts such as a CLI and terminal UI.

Why Run67 Exists

Enterprise systems often have many components and operational procedures that turn into long, fragile CLI argument sets. Run67 lets users own reusable runbooks that orchestrate established tools such as az, docker, ssh, sudo, and shell commands without replacing those tools' authentication and privilege models.

Run67 focuses on preparing a complete plan, showing it to a human, and then executing it through a structured event stream.

Current Capabilities

• Flow resources
• Native JSON, YAML, TOML, and XML resource formats with one canonical binder
• Optional adjacent JSON Schema subset and XSD validation
• Native call composition
• Pure reusable Function resources with fn("resource", name: expression)
• Typed Monitor resources with operational output limits and immutable MonitorSnapshot values
• GreenScreen live Monitor tabs with typed tables and approval-gated Flow row actions
• Safe Run67 expressions with ${{ ... }}
• Typed RunValue model
• Persistent JSON user state with get, set, and atomic local increment
• Root-Flow input initialization with pure calculation and exactly-once state allocation
• Native scalar input constraints, typed allowed-value editors, and collapsible advanced inputs
• Complete transitive planning
• Definition and invocation digests
• Digest-based approvals
• Trusted project-local .run67 resource scopes
• Approval-gated prerequisite validation Flows
• Structured runtime events
• Durable filesystem Run Records with typed snapshots, event journals, step history, plain transcripts, compatibility analysis, and explicit linked-Run resume
• Immutable exact-ID Publications for audited public value and artifact exchange between Runs
• Local captured commands
• Terminal-mode process abstraction
• Reusable Target resources
• Local, SSH, Docker, and SSH to Docker execution routes
• Approval digests that include resolved non-local destinations
• run67cli CLI host
• run67 Cameek.GreenScreen terminal UI host

Architecture

Cameek.Run67.Cli ───────────────┐
  │                      │
  ├─ Cameek.Run67.Formats       ▼
  └─ Cameek.Run67.Targets  Cameek.Run67.Core

Cameek.Run67.GreenScreen ───────┘
  │
  ├─ Cameek.Run67.Formats
  ├─ Cameek.Run67.Targets
  └─ Cameek.GreenScreen 0.1.9

Cameek.Run67.Core is UI-independent. Cameek.Run67.Formats binds native JSON/YAML/TOML/XML into canonical Core resources through one neutral object model and binder. Cameek.Run67.Targets compiles resolved routes into external ssh and docker CLI invocations. Cameek.Run67.GreenScreen is a host, not the execution engine.

All four resource formats have identical planning, digest, approval, and execution semantics. See resource formats for suffixes, native parser subsets, XML mapping, sidecar schemas, examples, and runnable demos.

Quick Start

Development requires a stable .NET 10 SDK. The repository SDK baseline and roll-forward policy are defined in global.json.

dotnet build Cameek.Run67.sln
dotnet test Cameek.Run67.sln

Install the Run67 tool

Published releases install the run67 command from NuGet.org:

dotnet tool install \
  --global \
  Cameek.Run67.Tool

Install the initial stable version explicitly with:

dotnet tool install \
  --global \
  --version 0.0.1 \
  Cameek.Run67.Tool

For a local development package, build the four-package feed first:

.scripts/pack-run67-tool.sh

dotnet tool install \
  --global \
  --add-source artifacts/nuget \
  --version 0.0.1 \
  Cameek.Run67.Tool

See installation and local-feed testing for update, uninstall, PATH, isolation, and WSL2 instructions.

Run the CLI through the project:

dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- validate examples/yaml/main/.run67/hello.run67.yaml
dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- plan examples/yaml/main/.run67/composed-parent.run67.yaml
dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- plan examples/toml/main/.run67/function-docker-allocation.run67.toml
dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- plan examples/xml/main/.run67/create-ubuntu24-container.run67.xml
dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- run examples/json/main/.run67/composed-parent.run67.json --param name=Mirek
dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- monitor examples/yaml/main/.run67/monitors/docker-containers.run67.yaml
dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- runs resume-check <run-id> examples/yaml/main/.run67/composed-parent.run67.yaml --param name=Mirek
dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- runs resume <run-id> examples/yaml/main/.run67/composed-parent.run67.yaml --param name=Mirek
dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- publications list
dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- plan examples/native-formats/flagship.run67.toml
dotnet run --project src/Cameek.Run67.Cli/Cameek.Run67.Cli.csproj -- plan examples/native-formats/mixed/parent.run67.yaml

After building, the executable names are run67cli and run67 in their project output folders.

dotnet run --project src/Cameek.Run67.GreenScreen/Cameek.Run67.GreenScreen.csproj
dotnet run --project src/Cameek.Run67.GreenScreen/Cameek.Run67.GreenScreen.csproj -- examples/yaml/main/.run67/composed-parent.run67.yaml --param name=Mirek

Running run67 without a resource opens a full-screen searchable flow browser. It loads user resources from ~/.run67 and, after an explicit path-specific trust decision, project resources from the nearest ancestor .run67 directory. Project and User remain distinct browser scopes. The browser retains invalid resource files for inspection and fuzzy-filters the tree while keeping matching ancestors visible. Preview and Enter prepare a fresh non-executable preview; Run67 continues through mandatory Plan Review and approval, so no browser action executes a Flow directly.

The GreenScreen workspace always keeps 📚 Flows as its first visible tab (stable layout ID explorer) and can add Editor, plain Text, approval-safe Favorites, and live Monitor tabs from a user or trusted-project layout.yaml. Flows and Editor provide explicit Run67, Preview, and editing actions: Preview ends in a non-executable Flow Review / Commands dialog, while Run67 keeps the normal input, Plan Review, prerequisite, approval, and execution pipeline. F5 reloads resources and layout. See GreenScreen layout tabs and Monitors.

When the selected root Flow declares non-sensitive inputs, GreenScreen opens a responsive Run67 Inputs form before Plan Review. Defaults are shown in Auto, missing required values start in Override, and supplied values may be edited or reset to Auto. Native constraints are validated consistently, allowedValues use typed drop-downs, and advanced rows can be collapsed. Root initSteps may reserve state values before the form after static closure and descriptor validation; only missing init-dependent inputs block that reservation. Pure dependent Auto previews update without allocating again, and pending, unavailable, or invalid previews disable confirmation. Sensitive inputs remain externally supplied and never enter visible editor state. See docs/interactive-inputs.md.

Plan Review summarizes the prepared flow, displays the wrapped execution plan, prerequisite state, and all preparation diagnostics in independently scrollable panes, shows whether execution is eligible, and retains the optional Return to Run67 App choice. It also offers opt-in [ ] Wizard mode Pause seconds: [ 3 ] controls. A non-negative pause is required only while Wizard mode is enabled; 0 keeps the panel without delaying execution. Preparation errors disable execution directly in the review; warnings and informational diagnostics remain visible without blocking the run. Run67 is the explicit action that executes approval-gated prerequisite checks and automatically continues to main approval/execution when required checks pass.

After approval, Run67 disposes the full-screen terminal application before execution begins and writes the execution outline and captured output directly to the ordinary shell. When Wizard mode is enabled, each executable main-flow step first shows a fixed shell panel with its title (or id), description, and an animated countdown. confirm steps show the panel and proceed directly to the normal prompt without waiting. Ctrl+C cancels an active countdown through the normal Run cancellation path. Wizard mode is GreenScreen presentation only; normal CLI/API execution is unchanged unless another host explicitly uses Core's optional step-presentation hook. Terminal commands run through Cameek.GreenScreen PTY hosting with no Run67 execution overlay or F10 menu, so the child owns keyboard input. When the selected flow finishes, Run67 prints a timestamped final lifecycle line with elapsed time. By default it exits to the invoking shell; selecting Return to Run67 App after execution starts a fresh catalog application after the shell run.

run steps default to captured interaction. Captured commands are for noninteractive output capture and must not wait for terminal input. Commands that may prompt—including sudo, SSH authentication, installers, shells, and REPLs—must explicitly declare interaction: terminal. For example:

run:
  interaction: terminal
  executable: sudo
  arguments:
    - apt-get
    - update

Use an explicit shell wrapper when shell syntax is required:

run:
  interaction: terminal
  executable: bash
  arguments:
    - -c
    - sudo -v && sudo apt-get update

The wrapper is explicit because Run67 otherwise executes an executable plus an argument array and does not interpret shell syntax. Password prompts normally do not echo typed characters because the child controls its terminal behavior. PTY keystrokes and screen output are deliberately not copied into Run67 events, transcript.log, or other Run Record data. A captured command that intentionally uses sudo without prompting should pass --non-interactive or -n; Run67 does not rewrite command arguments.

Steps can publish small typed values through the private RUN67_OUTPUTS directory. Declare the output beside run, write one file whose name exactly matches the declaration, and consume it through the existing step-output namespace:

- id: detect
  outputs:
    packageManager:
      type: string
      required: true
  run:
    executable: bash
    arguments:
      - -c
      - printf '%s' apt > "$RUN67_OUTPUTS/packageManager"

- id: consume
  run:
    executable: printf
    arguments:
      - '%s\n'
      - "${{ steps.detect.outputs.packageManager }}"

The same declaration and downstream expression work for local, direct SSH, and direct Docker execution, including terminal steps. See the resource model and the target-independent JDK flow with its local, SSH, and Docker launchers.

Before a terminal child starts, Run67 synchronously writes and flushes its complete redacted command preview. Multiline arguments use indexed, descriptive blocks so later positional arguments cannot appear as part of the script text. Each terminal-interaction step normally creates a separate PTY, and sudo authentication may therefore be requested again in another terminal step. A Flow can explicitly select terminalSession: flow when distinct terminal-step processes need one TTY identity. GreenScreen supports this scope for local, direct SSH, and direct Docker routes. Direct SSH uses one normal OpenSSH authentication, one encrypted master transport, one remote PTY, and a separate private control channel. Direct Docker binds one already-running container ID and uses one docker exec -it PTY plus one docker exec -i control channel. Both require only /bin/sh, /dev/tty, and documented basic POSIX utilities in the target environment. Each terminal step is still a separate process, so an exited shell, GT.M/YottaDB process, runmqsc, or other interactive application does not remain alive for the next step. Step isolation remains the default; Flow scope is isolated per called Flow invocation and creates a resume boundary at its first terminal step.

Example Flow

apiVersion: run67/v1
kind: Flow

metadata:
  namespace: examples
  name: parent

inputs:
  name:
    type: string
    default: World
  pullPolicy:
    type: string
    default: missing
    allowedValues: [always, missing, never]
    isAdvanced: true

steps:
  - id: child
    title: Run child flow
    description: Pass the selected name to the reusable child operation.
    call:
      flow: ./child.run67.yaml
      inputs:
        name: ${{ inputs.name }}

Example Function

apiVersion: run67/v1
kind: Function

metadata:
  namespace: examples.functions
  name: ssh-port

inputs:
  index:
    type: integer
    required: true

returns:
  type: integer
  value: ${{ 2200 + inputs.index }}

Flows call Functions through the expression engine:

value: >-
  ${{
    fn("./functions/ssh-port.run67.yaml", index: steps.allocate.outputs.value)
  }}

See docs/product-scope.md, docs/formats.md, docs/run-records.md, docs/publications.md, docs/interactive-inputs.md, docs/functions.md, docs/monitors.md, docs/project-flows.md, and docs/prerequisites.md.

Security Model

Run67 files are executable procedures. Preparation resolves the full transitive plan before execution, including sub-flows, targets, and Functions. Hosts can run once, approve an approval digest and run, or cancel. Changing any execution-relevant dependency changes the definition digest and invalidates stored approval. Changing a non-local execution destination changes the approval digest even when the Flow source is unchanged.

Run67 does not install or download remote resources. http://, https://, git://, and github: resource references are rejected.

Project trust, prerequisite approval, and main-flow approval are separate decisions. Untrusted project resources are not loaded, and Preview never executes prerequisite checks.

Sensitive inputs are redacted from known display/log surfaces. Run67 redacts known sensitive values and direct propagated values; it is not a complete data-loss-prevention system.

Monitor preparation does not execute source commands. Invalid decoder configuration fails during preparation, oversized Monitor stdout/stderr terminates the source capture, and structured Monitor CLI output keeps stdout machine-readable.

Current Limitations

• Supported route shapes are limited to local, SSH, Docker, and SSH to Docker.
• Target routes must be fully resolved during preparation.
• No Wizard resources
• No advanced Monitor aggregation, joins, or snapshot history
• Cleanup and quarantine are explicit manual actions; no automatic Run Record/Publication retention scheduler exists
• The canonical history and Publication catalogs are filesystem-based; Core ships with no SQLite dependency
• Explicit compatible resume creates a new linked Run and never modifies its source
• Captured command output persistence is opt-in; captured commands are noninteractive by contract
• Interactive PTY screen output and keystrokes are not recorded
• GreenScreen plan and approval dialogs are modal. Interactive child process routing is delegated to Cameek.GreenScreen InteractiveProcessHost; resize and escape-sequence behavior follow that public host.

Roadmap

See docs/roadmap.md.