mirror of
https://github.com/dtzp555-max/ocp.git
synced 2026-07-19 09:44:07 +00:00
feat(upgrade): ocp doctor + cross-version ocp update + rollback + AI prompts (#91)
* feat(doctor): add ocp doctor with --json + next_action contract Implements scripts/doctor.mjs with semver-aware path selection (noop/update/upgrade/fresh_install/fix_oauth/fix_service) and the JSON contract documented in the design spec. Service health + OAuth checks integrated; mockable via opts.mockHealth for unit tests. 8 unit tests cover the kind dispatch tree and the next_action shape for each kind. No cli.js citation needed: this is OCP-internal tooling with no corresponding cli.js operation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(ocp): wire cmd_doctor into bash CLI; dispatch to scripts/doctor.mjs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(doctor): handle unparseable version + empty health body Three issues raised by code-quality reviewer onb65201b: 1. semverCompare returned 0 for unparseable input, causing fromSupported=true and kind=noop for an install with unreadable package.json. Now treats unparseable currentVersion as fresh_install candidate. 2. mockHealth: { status: 200, body: null } routed to fix_oauth (because health.body?.auth?.ok was undefined → falsy). 200 with empty body is server-broken, not OAuth-broken; now routes to fix_service. 3. Removed unused KIND_ENUM declaration (dead code). Two regression tests added. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(upgrade): add scripts/upgrade.mjs + scripts/lib/snapshot.mjs Implements the upgrade dispatcher (noop / dry-run / light delegation / full path) and the snapshot writer/reader/list module. Full path snapshots plist + db + admin-key + openclaw.json before mutating, runs the 6 phases (pre-flight, snapshot, fetch+install, reconfigure, restart, post-flight), and emits a heads-up before launchctl bootout per notify_before_prod_service_restart.md policy. mockExec/mockDoctor injection points let tests verify the phase ordering without touching the real shell. fresh_install + rollback paths are deferred to Bundle 3. No cli.js citation needed: this is OCP-internal upgrade tooling with no corresponding cli.js operation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(upgrade): error path completeness + observability 5 issues raised by code-quality reviewer onc12013a: A. exec() wrapper now captures stderr from execSync failures and re-throws with `phase X failed: <stderr>` instead of the terse "Command failed: ..." default. Operators see the actual git/npm error. B. runFullUpgrade body wrapped in try/catch; any error after phase 2 (snapshot written) carries snapshotPath + phases + hint pointing at `ocp update --rollback`. Aligns with the post-flight failure pattern. C. CLI entrypoint now prints snapshotPath + hint on error. Plus minor: - snapshot.mjs tryCopy logs a [snapshot] warn line instead of silently swallowing copy errors (e.g. permission-denied admin-key) - heads-up window 1s → 3s, more operable per the policy intent - opts.yes intent comment added (Bundle 3 will use) One regression test added. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(upgrade): fresh-install + rollback paths Implements the two missing branches of runUpgrade dispatcher: - runFreshInstall: gated by --yes, runs doctor.next_action.ai_executable steps in order, fails fast on first error, attaches steps[] to thrown errors. Accepts mockExec for unit tests. - runRollback: locates latest or named snapshot in ~/.ocp/, reads from-commit.txt, restores plist + db + admin-key + service file (with per-file warn lines on copy failure), git-checkouts the from-commit, npm installs at that revision, restarts the service. --list shows all snapshots; --dry-run prints the plan without mutation. Both paths use the same exec() error-wrap pattern as runFullUpgrade (stderr capture, phases attached to thrown errors, restart heads-up). CLI entrypoint extended to parse --rollback / --list / --target / and optional positional snapshot path after --rollback. 6 unit tests cover: --yes gate, fresh_install ai_executable run, --rollback --list, no-snapshots error, --rollback --dry-run, mock-exec restore. No cli.js citation needed: this is OCP-internal upgrade tooling with no corresponding cli.js operation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore(upgrade): nit fixes from Bundle 3 code-quality review 3 micro-fixes on48e9408: 1. Remove unused mkdirSync import 2. snapshot-not-found error message hints "must be inside ~/.ocp/upgrade-snapshot-*" 3. runFreshInstall failure now includes e.stderr (or e.message fallback) in the thrown error and steps[].error so non-interactive callers see the actual reason Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * refactor(ocp): cmd_update dispatches via doctor; --rollback added; light path preserved cmd_update now calls scripts/doctor.mjs to determine which path to take: noop → "already at latest" exit 0 update → existing light path (git pull + npm install + restart), extracted into _cmd_update_light helper to keep the daily case fast and shell-only upgrade → exec node scripts/upgrade.mjs (full path with snapshot + post-flight) fresh_install → exec node scripts/upgrade.mjs (gated by --yes) fix_oauth/fix_service → print error referring user to `ocp doctor` cmd_update --rollback path: exec node scripts/upgrade.mjs --rollback "$@" forwards remaining args (--list, --dry-run, optional snapshot path). cmd_update_help expanded to document new flags. cmd_update --check fast path is preserved exactly (no doctor call there). No cli.js citation needed: this is OCP-internal CLI dispatch with no corresponding cli.js operation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(ocp): forward all args to cmd_update so multi-flag invocations work Bug found via runtime smoke test: ./ocp update --rollback --list → "no snapshots" (wrong; should list) Root cause: dispatch was `cmd_update "\${1:-}"` (only first arg). When user typed `--rollback --list`, cmd_update only received `--rollback`, the shift left $@ empty, and exec node ... --rollback got no flags. Other commands using "\${1:-}" don't need multi-arg, but cmd_update now does (--rollback --list, --rollback --dry-run, --target X --yes, etc.). Change: dispatch is now `cmd_update "\$@"`. cmd_update internals already handle multi-arg correctly (\$1 == --check fast path; \$1 == --rollback shift+forward; otherwise doctor-driven). Verified: ./ocp update --check → existing behaviour preserved ./ocp update --rollback --list → "Found 0 snapshots:" exit 0 ./ocp update --rollback --dry-run → no-snapshot error exit 1 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs(release): v3.15.0 — README AI prompt blocks + Upgrading rewrite + CHANGELOG §Installation, §Upgrading, §Troubleshooting each start with a copy-paste AI prompt block for Claude Code / Cursor / Copilot. The Upgrading section explains the three paths (light / full / fresh-install) and rollback usage. All Commands table gains an `ocp doctor` row. package.json bumped to 3.15.0. CHANGELOG.md gains the v3.15.0 entry covering doctor, the cross-version update path, --rollback, fresh-install routing, and AI prompt blocks. Notes the dependency on PR #90 (plist env merge bug fix, already merged). No cli.js citation needed: docs + version bump only, no server.mjs change. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(readme): show --yes in rollback usage examples Per Iron Rule 10 reviewer nit on PR #91: live rollback requires --yes even for interactive humans. Update §Upgrading examples to show the canonical human form. (AI agents pass --yes by convention; humans were hitting a confusing "requires --yes" error following the prior README.) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(scripts): CLI entrypoint guard resilient to symlinked install paths Bug found via integration test on MacBook Pro (macOS /tmp → /private/tmp): `import.meta.url === \`file://\${process.argv[1]}\`` evaluates false when the install path traverses a symlink, because import.meta.url is canonicalised but process.argv[1] is not. Result: ./ocp doctor (and ./ocp update via upgrade.mjs) exit silently with code 0 and no output, instead of running. Fix: use fileURLToPath + realpathSync on both sides of the comparison. Affects any install at a symlinked path (/tmp, NFS mounts, /var/ paths, docker bind mounts, etc.). Normal ~/ocp installs were unaffected. No cli.js citation needed: this is OCP-internal CLI dispatch with no corresponding cli.js operation. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
dtzp555-max
@@ -574,6 +574,263 @@ test("mergeSystemdEnv is idempotent", () => {
|
||||
assert.equal(mergeSystemdEnv(r1, SAMPLE_TEMPLATE_SYSTEMD), r1);
|
||||
});
|
||||
|
||||
// ── Doctor JSON Contract Tests ──
|
||||
import { runDoctor } from "./scripts/doctor.mjs";
|
||||
|
||||
console.log("\nDoctor:");
|
||||
|
||||
test("doctor --json shape: required top-level keys", async () => {
|
||||
const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.10.0", mockLatest: "v3.14.0" });
|
||||
for (const k of ["schema_version", "ready_to_upgrade", "current_version", "latest_version",
|
||||
"from_version_supported", "fail_count", "warn_count", "checks", "next_action"]) {
|
||||
assert.ok(k in result, `missing key: ${k}`);
|
||||
}
|
||||
assert.equal(result.schema_version, "1");
|
||||
});
|
||||
|
||||
test("doctor detects from-version < v3.4.0 → fresh_install", async () => {
|
||||
const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.2.0", mockLatest: "v3.14.0" });
|
||||
assert.equal(result.from_version_supported, false);
|
||||
assert.equal(result.next_action.kind, "fresh_install");
|
||||
assert.ok(Array.isArray(result.next_action.ai_executable));
|
||||
assert.ok(result.next_action.ai_executable.length > 0);
|
||||
});
|
||||
|
||||
test("doctor next_action.kind enum is one of allowed values", async () => {
|
||||
const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.10.0", mockLatest: "v3.14.0" });
|
||||
const ALLOWED = ["noop", "update", "upgrade", "fresh_install", "fix_oauth", "fix_service"];
|
||||
assert.ok(ALLOWED.includes(result.next_action.kind), `kind=${result.next_action.kind} not in enum`);
|
||||
});
|
||||
|
||||
test("doctor noop when current==latest", async () => {
|
||||
const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.14.0", mockLatest: "v3.14.0" });
|
||||
assert.equal(result.next_action.kind, "noop");
|
||||
assert.equal(result.ready_to_upgrade, true);
|
||||
});
|
||||
|
||||
test("doctor patch-bump same minor → update kind", async () => {
|
||||
const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.14.0", mockLatest: "v3.14.1" });
|
||||
assert.equal(result.next_action.kind, "update");
|
||||
});
|
||||
|
||||
test("doctor cross-minor → upgrade kind", async () => {
|
||||
const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.10.0", mockLatest: "v3.14.0" });
|
||||
assert.equal(result.next_action.kind, "upgrade");
|
||||
});
|
||||
|
||||
test("doctor OAuth FAIL → fix_oauth kind", async () => {
|
||||
const result = await runDoctor({
|
||||
skipNetwork: false,
|
||||
mockVersion: "v3.10.0",
|
||||
mockLatest: "v3.14.0",
|
||||
mockHealth: { status: 200, body: { auth: { ok: false, message: "ENOEXEC" } } }
|
||||
});
|
||||
assert.equal(result.next_action.kind, "fix_oauth");
|
||||
assert.ok(result.next_action.ai_executable.some(c => c.includes("install.cjs")));
|
||||
});
|
||||
|
||||
test("doctor service down → fix_service kind", async () => {
|
||||
const result = await runDoctor({
|
||||
skipNetwork: false,
|
||||
mockVersion: "v3.10.0",
|
||||
mockLatest: "v3.14.0",
|
||||
mockHealth: { error: "ECONNREFUSED" }
|
||||
});
|
||||
assert.equal(result.next_action.kind, "fix_service");
|
||||
});
|
||||
|
||||
test("doctor unparseable version → fresh_install", async () => {
|
||||
const result = await runDoctor({ skipNetwork: true, mockVersion: "garbage", mockLatest: "v3.14.0" });
|
||||
assert.equal(result.from_version_supported, false);
|
||||
assert.equal(result.next_action.kind, "fresh_install");
|
||||
});
|
||||
|
||||
test("doctor empty health body → fix_service (not fix_oauth)", async () => {
|
||||
const result = await runDoctor({
|
||||
skipNetwork: false,
|
||||
mockVersion: "v3.10.0",
|
||||
mockLatest: "v3.14.0",
|
||||
mockHealth: { status: 200, body: null }
|
||||
});
|
||||
assert.equal(result.next_action.kind, "fix_service");
|
||||
});
|
||||
|
||||
// ── Upgrade Tests ──
|
||||
import { runUpgrade } from "./scripts/upgrade.mjs";
|
||||
|
||||
console.log("\nUpgrade:");
|
||||
|
||||
test("upgrade --dry-run prints plan, no side effects", async () => {
|
||||
const result = await runUpgrade({
|
||||
dryRun: true,
|
||||
yes: true,
|
||||
mockDoctor: { ready_to_upgrade: true, next_action: { kind: "upgrade" }, current_version: "v3.10.0", latest_version: "v3.14.0" }
|
||||
});
|
||||
assert.equal(result.executed, false);
|
||||
assert.ok(result.plan.length > 0);
|
||||
assert.ok(result.plan.some(line => line.toLowerCase().includes("snapshot")));
|
||||
});
|
||||
|
||||
test("upgrade noop returns early when current==latest", async () => {
|
||||
const result = await runUpgrade({
|
||||
yes: true,
|
||||
mockDoctor: { ready_to_upgrade: true, next_action: { kind: "noop" }, current_version: "v3.14.0", latest_version: "v3.14.0" }
|
||||
});
|
||||
assert.equal(result.path, "noop");
|
||||
assert.equal(result.executed, true);
|
||||
assert.equal(result.changed, false);
|
||||
});
|
||||
|
||||
test("upgrade aborts on doctor FAIL", async () => {
|
||||
await assert.rejects(async () => {
|
||||
await runUpgrade({
|
||||
yes: true,
|
||||
mockDoctor: { ready_to_upgrade: false, fail_count: 1, next_action: { kind: "fix_oauth" } }
|
||||
});
|
||||
}, /doctor FAIL/);
|
||||
});
|
||||
|
||||
test("upgrade full path executes 5 phases", async () => {
|
||||
const result = await runUpgrade({
|
||||
yes: true,
|
||||
dryRun: false,
|
||||
mockExec: true,
|
||||
mockDoctor: { ready_to_upgrade: true, next_action: { kind: "upgrade" },
|
||||
current_version: "v3.10.0", latest_version: "v3.14.0" }
|
||||
});
|
||||
assert.equal(result.path, "upgrade");
|
||||
// Plan asks for 6 phases by name; verify each appears as a phase entry
|
||||
const phaseNames = result.phases.map(p => p.name);
|
||||
for (const expected of ["pre-flight", "snapshot", "fetch+install", "reconfigure", "restart", "post-flight"]) {
|
||||
assert.ok(phaseNames.includes(expected), `missing phase: ${expected}; got ${phaseNames.join(",")}`);
|
||||
}
|
||||
});
|
||||
|
||||
// ── Snapshot Tests ──
|
||||
import { writeSnapshot, readSnapshot, listSnapshots } from "./scripts/lib/snapshot.mjs";
|
||||
import { mkdtempSync, rmSync, mkdirSync as tMkdirSync, writeFileSync as testWriteFile } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join as testJoin } from "node:path";
|
||||
|
||||
console.log("\nSnapshot:");
|
||||
|
||||
test("writeSnapshot creates dir + manifest files", () => {
|
||||
const root = mkdtempSync(testJoin(tmpdir(), "ocp-snap-test-"));
|
||||
const dotOcp = testJoin(root, ".ocp");
|
||||
tMkdirSync(dotOcp, { recursive: true });
|
||||
testWriteFile(testJoin(dotOcp, "ocp.db"), "fake-sqlite-bytes");
|
||||
|
||||
const path = writeSnapshot({
|
||||
homeDir: root,
|
||||
fromCommit: "abc1234",
|
||||
fromVersion: "v3.10.0",
|
||||
toVersion: "v3.14.0",
|
||||
extraFiles: []
|
||||
});
|
||||
const m = readSnapshot(path);
|
||||
assert.equal(m.fromCommit, "abc1234");
|
||||
assert.equal(m.fromVersion, "v3.10.0");
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
test("listSnapshots returns sorted by ISO timestamp", () => {
|
||||
const root = mkdtempSync(testJoin(tmpdir(), "ocp-snap-list-"));
|
||||
const dotOcp = testJoin(root, ".ocp");
|
||||
tMkdirSync(dotOcp, { recursive: true });
|
||||
for (const ts of ["2026-05-01T10:00:00Z", "2026-05-02T10:00:00Z", "2026-05-03T10:00:00Z"]) {
|
||||
tMkdirSync(testJoin(dotOcp, `upgrade-snapshot-${ts}`));
|
||||
}
|
||||
const list = listSnapshots(root);
|
||||
assert.equal(list.length, 3);
|
||||
assert.ok(list[0].path.includes("2026-05-01"));
|
||||
assert.ok(list[2].path.includes("2026-05-03"));
|
||||
rmSync(root, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
test("upgrade error after snapshot carries snapshotPath + hint", async () => {
|
||||
// Use mockExec=true so no real commands are run.
|
||||
// Verify the success path returns a snapshotPath (Fix B regression guard).
|
||||
const result = await runUpgrade({
|
||||
yes: true,
|
||||
dryRun: false,
|
||||
mockExec: true,
|
||||
mockDoctor: { ready_to_upgrade: true, next_action: { kind: "upgrade" },
|
||||
current_version: "v3.10.0", latest_version: "v3.14.0" }
|
||||
});
|
||||
assert.ok(result.snapshotPath, "successful upgrade returns snapshotPath");
|
||||
assert.equal(result.path, "upgrade");
|
||||
assert.equal(result.executed, true);
|
||||
});
|
||||
|
||||
test("upgrade fresh_install requires --yes for non-interactive", async () => {
|
||||
await assert.rejects(async () => {
|
||||
await runUpgrade({
|
||||
yes: false,
|
||||
mockExec: true,
|
||||
mockDoctor: { ready_to_upgrade: false, from_version_supported: false,
|
||||
next_action: { kind: "fresh_install", ai_executable: ["echo would-rm-rf"] },
|
||||
current_version: "v3.2.0", latest_version: "v3.14.0" }
|
||||
});
|
||||
}, /requires --yes/);
|
||||
});
|
||||
|
||||
test("upgrade fresh_install with --yes runs ai_executable", async () => {
|
||||
const result = await runUpgrade({
|
||||
yes: true,
|
||||
mockExec: true,
|
||||
mockDoctor: { ready_to_upgrade: false, from_version_supported: false,
|
||||
next_action: { kind: "fresh_install",
|
||||
ai_executable: ["echo step-1", "echo step-2", "echo step-3"] },
|
||||
current_version: "v3.2.0", latest_version: "v3.14.0" }
|
||||
});
|
||||
assert.equal(result.path, "fresh_install");
|
||||
assert.equal(result.steps.length, 3);
|
||||
});
|
||||
|
||||
test("rollback --list returns snapshots", async () => {
|
||||
const result = await runUpgrade({
|
||||
rollback: true,
|
||||
list: true,
|
||||
mockSnapshots: [
|
||||
{ name: "upgrade-snapshot-2026-05-01T10:00:00Z", path: "/tmp/snap-1" },
|
||||
{ name: "upgrade-snapshot-2026-05-02T10:00:00Z", path: "/tmp/snap-2" }
|
||||
]
|
||||
});
|
||||
assert.equal(result.path, "rollback-list");
|
||||
assert.equal(result.snapshots.length, 2);
|
||||
});
|
||||
|
||||
test("rollback with no snapshots fails clearly", async () => {
|
||||
await assert.rejects(async () => {
|
||||
await runUpgrade({ rollback: true, dryRun: true, mockSnapshots: [] });
|
||||
}, /no upgrade snapshots/);
|
||||
});
|
||||
|
||||
test("rollback --dry-run produces a plan without mutation", async () => {
|
||||
const result = await runUpgrade({
|
||||
rollback: true,
|
||||
dryRun: true,
|
||||
mockSnapshots: [{ name: "upgrade-snapshot-2026-05-11T08:30:00Z", path: "/tmp/snap-x" }],
|
||||
mockSnapshotMeta: { fromCommit: "abc1234", fromVersion: "v3.10.0", toVersion: "v3.14.0", path: "/tmp/snap-x" }
|
||||
});
|
||||
assert.equal(result.path, "rollback-dry-run");
|
||||
assert.equal(result.executed, false);
|
||||
assert.ok(result.plan.length > 0);
|
||||
});
|
||||
|
||||
test("rollback latest snapshot restores files (mockExec)", async () => {
|
||||
const result = await runUpgrade({
|
||||
rollback: true,
|
||||
yes: true,
|
||||
mockExec: true,
|
||||
mockSnapshots: [{ name: "upgrade-snapshot-2026-05-11T08:30:00Z", path: "/tmp/snap-x" }],
|
||||
mockSnapshotMeta: { fromCommit: "abc1234", fromVersion: "v3.10.0", toVersion: "v3.14.0", path: "/tmp/snap-x" }
|
||||
});
|
||||
assert.equal(result.path, "rollback");
|
||||
assert.equal(result.executed, true);
|
||||
assert.ok(result.phases.some(p => p.name === "git-checkout"));
|
||||
});
|
||||
|
||||
// ── Cleanup ──
|
||||
closeDb();
|
||||
|
||||
|
||||
Reference in New Issue
Block a user