[Issue #112] [Feature]: Expose workspacePreparedAt in openclaw code run --json output

docs/openclawcode/README.md

@@ -91,6 +91,14 @@ loop with:
 - a local builder/verifier runtime adapter built on top of OpenClaw's embedded
   agent entrypoint
 - an `openclaw code run ...` CLI path for issue-driven execution
+- an `openclaw code bootstrap --repo owner/repo` CLI path for low-touch target
+  repo bootstrap, including:
+  - target repo clone/attach
+  - operator env/config materialization
+  - bootstrap repo binding persistence
+  - blueprint / role-routing / discovery / stage-gate seeding
+  - gateway startup attempt
+  - strict setup-check and built-startup proof summary
 - a versioned top-level JSON contract for `openclaw code run --json`, anchored
   by `contractVersion: 1` and documented in `run-json-contract.md`
 - a versioned machine-readable policy contract for:

docs/openclawcode/codex-openclawcode-install.md

@@ -41,12 +41,9 @@ entry or interactive approval:
 3. run:
    - `pnpm install`
    - `pnpm build`
-4. prepare a starter operator config and repo mapping
-5. run health checks:
-   - `./scripts/openclawcode-setup-check.sh --strict --json`
-   - `./scripts/openclawcode-setup-check.sh --strict --probe-built-startup --json`
-6. prepare the target repository checkout and show the exact
-   `openclaw code run ...` command to use
+4. run `openclaw code bootstrap --repo owner/repo --json`
+5. prepare the target repository checkout and show the exact
+   `openclaw code run ...` or chat command to use
 
 ## What The User Must Do
 
@@ -76,9 +73,8 @@ Requirements:
 - clone https://github.com/zhyongrui/openclawcode.git to ~/pros/openclawcode
 - run pnpm install
 - run pnpm build
-- run:
-  - ./scripts/openclawcode-setup-check.sh --strict --json
-  - ./scripts/openclawcode-setup-check.sh --strict --probe-built-startup --json
+- then run:
+  - openclaw code bootstrap --repo owner/repo --json
 
 Important repository constraint:
 - this is the forked OpenClaw checkout that contains openclawcode
@@ -95,9 +91,9 @@ When finished, report:
 - pnpm version
 - codex version
 - whether build passed
-- whether strict setup-check passed
-- whether built-startup proof passed
-- the exact next commands for binding or running against a new target repo
+- whether bootstrap completed
+- the bootstrap JSON summary
+- the exact next commands for binding or running against the new target repo
 ```
 
 ## Minimal Install Flow
@@ -108,10 +104,8 @@ The smallest successful machine bootstrap looks like this:
 2. Codex runs `pnpm install`.
 3. Codex runs `pnpm build`.
 4. The user provides `GH_TOKEN` or `GITHUB_TOKEN`.
-5. Codex runs strict setup-check.
-6. Codex runs built-startup setup-check.
-7. Codex prepares the target repo mapping.
-8. The user chooses CLI-only or chatops validation.
+5. Codex runs `openclaw code bootstrap --repo owner/repo --json`.
+6. The user chooses CLI-only or chatops validation.
 
 ## Lowest-Touch User Goal
 
@@ -122,7 +116,7 @@ The desired product outcome is even smaller than today's install flow:
 3. the user chooses `owner/repo`
 4. one bootstrap command configures the operator automatically
 
-That command is not fully productized yet. See
+That command now exists as an MVP, but it is not fully productized yet. See
 `single-login-bootstrap-proposal.md` for the intended end state and the split
 between `openclaw` and `openclawcode`.
 
@@ -137,10 +131,13 @@ There are two supported paths.
 
 Use this when you want the fastest proof on a new machine.
 
-1. clone the new target repo locally
-2. add a repo entry in the operator config, or pass the repo information
-   directly to the CLI
-3. run:
+1. run bootstrap for the target repo:
+
+```bash
+openclaw code bootstrap --repo <owner>/<repo> --json
+```
+
+2. then run:
 
 ```bash
 openclaw code blueprint-init --title "Project Blueprint" --goal "Describe the target goal"
@@ -151,15 +148,21 @@ openclaw code run --issue 123 --owner <owner> --repo <repo> --repo-root <absolut
 
 Use this when you want the real operator flow.
 
-1. bring up the local gateway
-2. connect the real chat surface
-3. bind the repo from the desired conversation:
+1. run bootstrap for the target repo, ideally with explicit chat target values:
+
+```bash
+openclaw code bootstrap --repo <owner>/<repo> --mode chatops --channel feishu --chat-target <target> --json
+```
+
+2. bring up the local gateway if bootstrap reported that it could not start it
+3. connect the real chat surface
+4. bind the repo from the desired conversation if bootstrap only created a placeholder binding:
 
 ```text
 /occode-bind <owner>/<repo>
 ```
 
-4. then use:
+5. then use:
 
 ```text
 /occode-intake

docs/openclawcode/dev-log/2026-03-17.md

@@ -554,3 +554,33 @@ The runbook now states explicitly that Codex must clone:
 It also now warns Codex not to search for a separate public repository named
 `openclawcode`, and to stop immediately if the checkout does not contain
 `scripts/openclawcode-setup-check.sh`.
+
+## Bootstrap MVP
+
+Implemented the first real `openclaw code bootstrap --repo owner/repo` command.
+
+What it now does automatically:
+
+- parses `owner/repo`
+- clones or attaches the target repository
+- persists `GH_TOKEN`, `OPENCLAWCODE_GITHUB_REPO`, and a generated
+  `OPENCLAWCODE_GITHUB_WEBHOOK_SECRET` into `~/.openclaw/openclawcode.env`
+- writes or updates the bundled `openclawcode` repo entry in `openclaw.json`
+- persists a bootstrap repo binding in `plugins/openclawcode/chatops-state.json`
+- seeds `PROJECT-BLUEPRINT.md` in the target repo when missing
+- refreshes role-routing, discovery, and stage-gate artifacts
+- attempts to start the local gateway
+- runs strict setup-check plus built-startup proof and returns the result
+  through `--json`
+
+What it still does not automate:
+
+- GitHub webhook create/reuse
+- OpenClaw-side GitHub login flow
+- provider credential onboarding
+- auto-detecting the real active chat target
+
+Validation for this bootstrap slice:
+
+- `pnpm exec vitest run src/commands/openclawcode.test.ts --pool threads`
+  passed (`92` tests)

docs/openclawcode/fresh-host-install.md

@@ -24,9 +24,8 @@ If you want Codex to perform this bootstrap on the fresh machine, use
 1. clone the repo
 2. install dependencies
 3. build once
-4. run strict setup-check
-5. configure the OpenClaw plugin repo binding
-6. validate one narrow issue locally before relying on webhook auto mode
+4. run `openclaw code bootstrap --repo owner/repo --json`
+5. validate one narrow issue locally before relying on webhook auto mode
 
 ## Lowest-Touch Fresh-Host Goal
 
@@ -37,20 +36,40 @@ The intended operator experience should eventually be:
 3. the user names the target repo
 4. `openclaw code bootstrap --repo owner/repo` handles the rest
 
-That full product path does not exist yet.
+That full product path is not complete yet, but there is now a real bootstrap
+MVP.
 
 Today, the shortest practical path is:
 
 1. Codex clones and builds this repo
 2. the user provides one GitHub token
-3. Codex writes the operator env file and bundled plugin repo config
-4. Codex runs strict setup-check and built-startup proof
-5. the user performs one narrow validation:
+3. Codex runs:
+
+```bash
+openclaw code bootstrap --repo owner/repo --json
+```
+
+4. the user performs one narrow validation:
    - CLI-only, or
    - one chat-side bind / read command if ChatOps is already connected
 
 See `single-login-bootstrap-proposal.md` for the target end state.
 
+## What Bootstrap Already Automates
+
+`openclaw code bootstrap --repo owner/repo` now handles:
+
+- target repo clone or attach
+- operator env persistence under `~/.openclaw/openclawcode.env`
+- bundled plugin repo config materialization in `openclaw.json`
+- placeholder or explicit repo binding persistence in `chatops-state.json`
+- `PROJECT-BLUEPRINT.md` scaffold creation in the target repo when missing
+- role-routing, discovery, and stage-gate artifact seeding
+- local gateway startup attempt
+- strict setup-check plus built-startup proof
+
+It still does not create or reuse the GitHub webhook automatically.
+
 ## Expected Healthy Outputs
 
 - `setup-check --strict --json` returns all required readiness signals

docs/openclawcode/run-json-contract.md

@@ -214,6 +214,9 @@ those nested objects.
 - `workspaceHasWorktreePath`
 - `workspaceWorktreePath`
 
+`workspacePreparedAt` mirrors `workspace.preparedAt` when that nested value exists
+and otherwise uses `null`.
+
 ### Pull Request And Merge State
 
 - `draftPullRequestBranchName`

docs/openclawcode/single-login-bootstrap-proposal.md

@@ -46,22 +46,39 @@ surface for a fresh machine or a new repo.
 
 ## Current Reality
 
-Today the repo still expects manual configuration in these areas:
+The repo now includes a first bootstrap command:
+
+```bash
+openclaw code bootstrap --repo owner/repo
+```
+
+The implemented MVP already does these pieces automatically:
+
+- clone or attach the target repo
+- persist `GH_TOKEN`, repo key, and a generated webhook secret into
+  `~/.openclaw/openclawcode.env`
+- materialize the bundled plugin repo entry inside `openclaw.json`
+- persist a bootstrap repo binding in `chatops-state.json`
+- seed `PROJECT-BLUEPRINT.md`, role-routing, discovery, and stage-gate artifacts
+- try to start the local gateway
+- run strict setup-check plus built-startup proof by default
+- emit a machine-readable bootstrap summary through `--json`
+
+What is still manual or only partially automated:
 
 - `docs/openclawcode/operator-setup.md`
-  - explicit `GH_TOKEN`
-  - explicit `OPENCLAWCODE_GITHUB_WEBHOOK_SECRET`
   - explicit `OPENCLAWCODE_GITHUB_HOOK_ID`
-  - explicit plugin repo entry in `openclaw.json`
+- provider credentials still come from the surrounding OpenClaw/operator login
 - `scripts/openclawcode-webhook-tunnel.sh`
   - rewrites an existing webhook
   - does not create the webhook for the operator
 - runtime repo binding
   - `/occode-bind` exists and works
-  - but it still comes after manual repo config/bootstrap
+  - bootstrap can seed a placeholder or explicit binding, but cannot yet
+    discover the active chat target on its own
 
-So the desired experience is clearly reachable, but not yet productized as one
-command.
+So the desired experience is now partially productized as one command, but it
+still stops short of the full single-login end state.
 
 ## Product Split
 
@@ -213,36 +230,38 @@ The first bootstrap should prefer safety over autonomy:
 
 ## Simplest Practical Path Today
 
-Until the full bootstrap command exists, the lowest-touch real workflow should
-be:
+With the current bootstrap MVP, the lowest-touch real workflow is:
 
 1. Codex clones and builds `zhyongrui/openclawcode`.
 2. The user provides one GitHub token.
-3. Codex writes:
-   - `~/.openclaw/openclawcode.env`
-   - `~/.openclaw/openclaw.json`
-4. Codex runs:
-   - `./scripts/openclawcode-setup-check.sh --strict --json`
-   - `./scripts/openclawcode-setup-check.sh --strict --probe-built-startup --json`
-5. If chat is already connected, the user sends one bind or verification
+3. Codex runs:
+   - `openclaw code bootstrap --repo owner/repo --json`
+4. If chat is already connected, the user sends one bind or verification
    command from the real conversation.
 
-That is the shortest currently achievable path without first implementing the
-bootstrap command.
+That is the shortest currently achievable path before webhook creation and chat
+target discovery are automated too.
 
 ## MVP Delivery Plan
 
 ### Phase 1: CLI-Only Bootstrap
 
-Ship:
+Status: shipped as MVP.
+
+Delivered:
 
-- GitHub credential reuse from `openclaw`
 - repo clone/attach
 - repo config materialization
-- strict setup-check
+- operator env persistence
+- placeholder or explicit repo binding persistence
+- strict setup-check and built-startup proof
 - `--json` output
+- blueprint + role-routing + discovery + stage-gate seeding
+
+Still missing inside this phase:
 
-Do not require ChatOps or webhook creation yet.
+- GitHub login handoff from `openclaw onboard`
+- zero-touch provider credential reuse
 
 ### Phase 2: Webhook Bootstrap
 

src/cli/program/register.code.ts

@@ -1,5 +1,6 @@
 import type { Command } from "commander";
 import {
+  openclawCodeBootstrapCommand,
   openclawCodeBlueprintClarifyCommand,
   openclawCodeBlueprintDecomposeCommand,
   openclawCodeBlueprintInitCommand,
@@ -52,6 +53,10 @@ export function registerCodeCommands(program: Command) {
         `
 ${theme.heading("Examples:")}
 ${formatHelpExamples([
+  [
+    "openclaw code bootstrap --repo owner/repo --json",
+    "Clone or attach a target repo, persist operator config, seed blueprint artifacts, and run readiness checks.",
+  ],
   [
     'openclaw code blueprint-init --title "OpenClawCode Blueprint" --goal "Ship blueprint-first autonomous development"',
     "Create the fixed repo-local project blueprint scaffold.",
@@ -161,6 +166,47 @@ ${theme.muted("Docs:")} ${formatDocsLink("/cli/code", "docs.openclaw.ai/cli/code
       code.help({ error: true });
     });
 
+  code
+    .command("bootstrap")
+    .description(
+      "Bootstrap a target repository into the local openclawcode operator with minimal manual setup",
+    )
+    .requiredOption("--repo <owner/repo>", "GitHub repo to bootstrap")
+    .option("--repo-root <dir>", "Target repository checkout path")
+    .option("--state-dir <dir>", "Operator state directory")
+    .option("--mode <mode>", "Bootstrap mode (auto, cli-only, chatops)", "auto")
+    .option("--channel <channel>", "Chat channel to bind immediately, such as feishu")
+    .option("--chat-target <target>", "Chat target identifier to persist for notifications")
+    .option("--base-branch <branch>", "Base branch for issue work")
+    .option("--builder-agent <id>", "Builder agent id to persist in repo config")
+    .option("--verifier-agent <id>", "Verifier agent id to persist in repo config")
+    .option("--test <command>", "Test command to persist in repo config", collectOption, [])
+    .option("--no-start-gateway", "Do not try to start the local gateway after writing config")
+    .option("--no-probe-built-startup", "Skip the isolated built-startup proof during setup-check")
+    .option("--json", "Output JSON", false)
+    .action(async (opts) => {
+      await runCommandWithRuntime(defaultRuntime, async () => {
+        await openclawCodeBootstrapCommand(
+          {
+            repo: opts.repo as string,
+            repoRoot: opts.repoRoot as string | undefined,
+            stateDir: opts.stateDir as string | undefined,
+            mode: opts.mode as "auto" | "cli-only" | "chatops",
+            channel: opts.channel as string | undefined,
+            chatTarget: opts.chatTarget as string | undefined,
+            baseBranch: opts.baseBranch as string | undefined,
+            builderAgent: opts.builderAgent as string | undefined,
+            verifierAgent: opts.verifierAgent as string | undefined,
+            test: (opts.test as string[] | undefined) ?? [],
+            startGateway: Boolean(opts.startGateway),
+            probeBuiltStartup: Boolean(opts.probeBuiltStartup),
+            json: Boolean(opts.json),
+          },
+          defaultRuntime,
+        );
+      });
+    });
+
   code
     .command("blueprint-init")
     .description("Create the fixed project blueprint scaffold in the current repo")