@namewta/speculo 1.0.20 → 1.0.21

package/template/workflows/ops/common/schemas/root-confirmation.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:root-confirmation:v1",
+  "type": "object",
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "artifact": {
+      "const": "ops-root-confirmation"
+    },
+    "receipt_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "host_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "platform": {
+      "enum": [
+        "linux",
+        "windows",
+        "darwin"
+      ]
+    },
+    "transport": {
+      "enum": [
+        "local",
+        "ssh"
+      ]
+    },
+    "identity": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "root": {
+      "type": "string",
+      "minLength": 1
+    },
+    "account": {
+      "type": "object",
+      "properties": {
+        "username": {
+          "type": "string",
+          "minLength": 1
+        },
+        "uid": {
+          "type": "string"
+        },
+        "home": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "username",
+        "uid",
+        "home"
+      ],
+      "additionalProperties": false
+    },
+    "endpoint_digest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "discovery": {
+      "type": "object",
+      "properties": {
+        "receipt_id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "maxLength": 80
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        }
+      },
+      "required": [
+        "receipt_id",
+        "digest"
+      ],
+      "additionalProperties": false
+    },
+    "confirmed_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "by": {
+      "type": "string",
+      "minLength": 1
+    },
+    "statement": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "schema_version",
+    "artifact",
+    "receipt_id",
+    "host_id",
+    "platform",
+    "transport",
+    "identity",
+    "root",
+    "account",
+    "endpoint_digest",
+    "discovery",
+    "confirmed_at",
+    "by",
+    "statement"
+  ],
+  "additionalProperties": false
+}

package/template/workflows/ops/common/schemas/server-connection.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:server-connection:v1",
+  "type": "object",
+  "properties": {
+    "platform": {
+      "enum": [
+        "linux",
+        "windows",
+        "darwin"
+      ]
+    },
+    "transport": {
+      "enum": [
+        "local",
+        "ssh"
+      ]
+    },
+    "connection": {
+      "type": "object",
+      "properties": {
+        "hostname": {
+          "type": "string",
+          "minLength": 1
+        },
+        "username": {
+          "type": "string",
+          "minLength": 1
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535
+        },
+        "known_hosts": {
+          "type": "string",
+          "minLength": 1
+        },
+        "identity_file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "node": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sudo": {
+          "type": "boolean"
+        },
+        "shell": {
+          "enum": [
+            "posix",
+            "powershell"
+          ]
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "platform",
+    "transport",
+    "connection"
+  ],
+  "additionalProperties": false
+}

package/template/workflows/ops/common/schemas/server-discovery.schema.json

@@ -0,0 +1,171 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:server-discovery:v1",
+  "type": "object",
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "artifact": {
+      "const": "ops-server-discovery"
+    },
+    "discovery_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "host_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "discovered_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "endpoint": {
+      "type": "object",
+      "properties": {
+        "host_id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "maxLength": 80
+        },
+        "platform": {
+          "enum": [
+            "linux",
+            "windows",
+            "darwin"
+          ]
+        },
+        "transport": {
+          "enum": [
+            "local",
+            "ssh"
+          ]
+        },
+        "connection": {
+          "type": "object",
+          "properties": {
+            "hostname": {
+              "type": "string",
+              "minLength": 1
+            },
+            "username": {
+              "type": "string",
+              "minLength": 1
+            },
+            "port": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 65535
+            },
+            "known_hosts": {
+              "type": "string",
+              "minLength": 1
+            },
+            "identity_file": {
+              "type": "string",
+              "minLength": 1
+            },
+            "node": {
+              "type": "string",
+              "minLength": 1
+            },
+            "sudo": {
+              "type": "boolean"
+            },
+            "shell": {
+              "enum": [
+                "posix",
+                "powershell"
+              ]
+            }
+          },
+          "required": [],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "host_id",
+        "platform",
+        "transport",
+        "connection"
+      ],
+      "additionalProperties": false
+    },
+    "endpoint_digest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "facts": {
+      "type": "object",
+      "properties": {
+        "identity": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "platform": {
+          "enum": [
+            "linux",
+            "windows",
+            "darwin"
+          ]
+        },
+        "username": {
+          "type": "string",
+          "minLength": 1
+        },
+        "uid": {
+          "type": "string"
+        },
+        "home": {
+          "type": "string",
+          "minLength": 1
+        },
+        "node": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "node_version": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "identity",
+        "platform",
+        "username",
+        "uid",
+        "home",
+        "node",
+        "node_version"
+      ],
+      "additionalProperties": false
+    },
+    "suggested_root": {
+      "type": "string",
+      "minLength": 1
+    },
+    "registered": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "schema_version",
+    "artifact",
+    "discovery_id",
+    "host_id",
+    "discovered_at",
+    "endpoint",
+    "endpoint_digest",
+    "facts",
+    "suggested_root",
+    "registered"
+  ],
+  "additionalProperties": false
+}

package/template/workflows/ops/common/schemas/spec.schema.json

@@ -160,6 +160,25 @@
                   ],
                   "additionalProperties": false
                 }
+              },
+              "root_confirmation": {
+                "type": "object",
+                "properties": {
+                  "receipt_id": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+                    "maxLength": 80
+                  },
+                  "digest": {
+                    "type": "string",
+                    "pattern": "^[a-f0-9]{64}$"
+                  }
+                },
+                "required": [
+                  "receipt_id",
+                  "digest"
+                ],
+                "additionalProperties": false
               }
             },
             "required": [

package/template/workflows/ops/common/schemas/status.schema.json

@@ -362,6 +362,25 @@
             ],
             "additionalProperties": false
           }
+        },
+        "root_confirmation": {
+          "type": "object",
+          "properties": {
+            "receipt_id": {
+              "type": "string",
+              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+              "maxLength": 80
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            }
+          },
+          "required": [
+            "receipt_id",
+            "digest"
+          ],
+          "additionalProperties": false
         }
       },
       "required": [

package/template/workflows/ops/common/templates/FLEET.html

@@ -47,7 +47,7 @@ function render(){const server=$("server").value,project=$("project").value,st=$
 const ds=data.deployments.filter(d=>(!server||d.server_id===server)&&(!project||d.project_id===project)&&(!st||d.status===st)&&match(d));
 const ss=data.servers.filter(s=>(!server||s.server_id===server)&&(!project||s.deployment_ids.some(id=>byDeployment.get(id)?.project_id===project))&&(!st||ds.some(d=>d.server_id===s.server_id))&&(match(s)||ds.some(d=>d.server_id===s.server_id)));
 const ps=data.projects.filter(p=>(!project||p.project_id===project)&&(!server||p.deployment_ids.some(id=>byDeployment.get(id)?.server_id===server))&&(!st||ds.some(d=>d.project_id===p.project_id))&&(match(p)||ds.some(d=>d.project_id===p.project_id)));
-table("servers",["服务器 / 名称","地址 / 系统","检查结果","检查详情（* 必需项）","项目","部署根"],ss.map(s=>[links("server",[s.server_id]),`${s.name} · ${s.address}${s.port?":"+s.port:""} / ${s.platform}`,badge(s.readiness),checks(s),links("project",s.project_ids),s.root]));
+table("servers",["服务器 / 名称","地址 / 系统","检查结果","检查详情（* 必需项）","项目","账号 / 持久化根 / 确认 / 文档"],ss.map(s=>[links("server",[s.server_id]),`${s.name} · ${s.address}${s.port?":"+s.port:""} / ${s.platform}`,badge(s.readiness),checks(s),links("project",s.project_ids),`${s.login_account} / ${s.root} / ${s.root_confirmation.status} / ${s.initialization.documents}`]));
 table("projects",["项目","名称","类别 / 服务类型","所在服务器","部署数量"],ps.map(p=>[link("project",p.project_id),p.name,`${p.kind} / ${p.service_type||"—"}`,links("server",p.server_ids),p.deployment_ids.length]));
 table("deployments",["部署实例","项目 / 服务器","环境 / 方法","记录状态","计划版本","验证版本","根目录 / 更新时间"],ds.map(d=>{const where=node("div");where.append(link("project",d.project_id),node("div"),link("server",d.server_id));return[d.deployment_id,where,`${d.environment} / ${d.instance} / ${d.method}`,badge(d.status),d.desired_version,d.observed_version,`${d.root} / ${d.updated_at||"未验证"}`];}));
 table("services",["服务器","主机级服务","类型","systemd 单元","监听端口"],ss.flatMap(s=>s.host_services.map(v=>[link("server",s.server_id),v.service_id,v.kind,v.unit,v.port])));

package/template/workflows/ops/common/templates/HOST-README.md

@@ -2,7 +2,9 @@
 
 此文件是内容合同，不含真实密码；实际生成器依据成功回执填入真实值，不把占位符当交付。
 
-## host_id、实际身份、host_root、更新 UTC 时间
+## host_id、实际身份、登录账号、host_root、根确认回执、更新 UTC 时间
+
+区分已登记、目录存在、双边文档已验证、项目运行环境就绪。新根由用户指定或接受实际登录主目录下 ops；已有根标记既有登记，换账号不换根。
 
 ## 服务一览表
 

package/template/workflows/ops/common/tests/test_ops.mjs

@@ -67,7 +67,7 @@ function setupFixture() {
     project_id: "app-a", display_name: "APP A", kind: "app", service_type: null,
     source: { type: "local", location: join(tmp, "source"), revision: "v1" },
   };
-  model.register(state, { hosts: [host], projects: [project] });
+  const legacy = model.load(state); legacy.hosts[host.host_id] = host; legacy.projects[project.project_id] = project; model.save(state, legacy); // pre-upgrade v3 fixture
   model.putCredential(state, { credential_id: "app-auth", version: 1, purpose: "Synthetic test only", values: { username: "app-user", password: PASSWORD } });
   const spec = (version = "v1", operation = "deploy", program = null) => {
     if (program == null) {
@@ -440,7 +440,7 @@ test("planner contracts", async (t) => {
   });
   await each("unrelated host registration does not block approval", (fx) => {
     const [info] = fx.plan();
-    model.register(fx.state, { hosts: [{ ...fx.host, host_id: "node-b", display_name: "Node B", root: join(fx.tmp, "server-b") }] });
+    const legacy = model.load(fx.state); legacy.hosts["node-b"] = { ...fx.host, host_id: "node-b", display_name: "Node B", root: join(fx.tmp, "server-b") }; model.save(fx.state, legacy); // preserve legacy multi-root executor coverage
     fx.approve(info);
   });
   await each("touched host catalog drift blocks approval", (fx) => {
@@ -888,7 +888,7 @@ test("control file helpers", () => {
 });
 
 test("disjoint host plans apply sequentially", () => runFx((fx) => {
-  model.register(fx.state, { hosts: [{ ...fx.host, host_id: "node-b", display_name: "Node B", root: join(fx.tmp, "server-b") }] });
+  const legacy = model.load(fx.state); legacy.hosts["node-b"] = { ...fx.host, host_id: "node-b", display_name: "Node B", root: join(fx.tmp, "server-b") }; model.save(fx.state, legacy); // preserve legacy multi-root executor coverage
   const specA = {
     schema_version: 1, worker: "H", operation: "maintain", hosts: ["node-a"], reason: "Host A cache fixture",
     rollback_note: "Keep isolated cache until a separate purge is approved.",

package/template/workflows/ops/common/tests/test_ops_bootstrap.mjs

@@ -14,6 +14,7 @@ import * as bootstrap from "../tools/opslib/bootstrap.mjs";
 import { initialize, main, cliHooks } from "../tools/opslib/cli.mjs";
 import * as agent from "../tools/opslib/agent.mjs";
 import * as model from "../tools/opslib/model.mjs";
+import { onboardingHooks, discoverServer, confirmServerRoot } from "../tools/opslib/onboarding.mjs";
 
 const toolsDir = join(dirname(fileURLToPath(import.meta.url)), "../tools");
 const scriptPath = join(toolsDir, "bootstrap-volta.sh");
@@ -258,9 +259,13 @@ function cliFixture({ executeLinux = false } = {}) {
   const archives = makeArchives(tmp);
   const prevPin = bootstrap.bootstrapHooks.loadPin;
   bootstrap.bootstrapHooks.loadPin = () => pinFor(archives);
+  const previousObserve = onboardingHooks.observe;
+  onboardingHooks.observe = (h, root) => ({ identity: executeLinux ? agent.fingerprint() : "a".repeat(64), platform: "linux", username: h.connection.username, uid: "1000", home: "/home/ops", node: null, node_version: null, ...(root ? {root_check: {exists: false, writable: true, nonempty: false, owner: null}} : {}) });
   return {
     tmp, state, target, kh, archives,
+    confirm(host) { const d = discoverServer(state, host.host_id, host); const r = confirmServerRoot(state, host.host_id, d.discovery.receipt_id, host.root, "fixture-user", "Confirm only this isolated simulated target root"); host.root_confirmation = r.root_confirmation; },
     cleanup() {
+      onboardingHooks.observe = previousObserve;
       bootstrap.bootstrapHooks.loadPin = prevPin;
       rmSync(tmp, { recursive: true, force: true });
     },
@@ -279,6 +284,7 @@ test("Linux SSH bootstrap and enrollment preserve remote paths on every controll
   const mock = mockTransport({ probeJson: missingProbe, applyJson: { status: "installed", connection_node: connectionNode, profile_unchanged: true } });
   try {
     const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    fx.confirm(host);
     const conn = writeConn(fx.tmp, host);
     const r = captureMain(["bootstrap-node", "--state", fx.state, "--host-id", host.host_id, "--connection-file", conn, "--apply", "--account", "ops", "--host-root", fx.target, "--ack", ACK,
       "--volta-archive", fx.archives.voltaTar, "--volta-sha256", fx.archives.voltaSha, "--node-archive", fx.archives.nodeTar, "--node-sha256", fx.archives.nodeSha]);
@@ -290,6 +296,15 @@ test("Linux SSH bootstrap and enrollment preserve remote paths on every controll
     assert.deepEqual(applyArgs.slice(applyArgs.indexOf("--apply") + 1), [paths[0], fx.archives.voltaSha, paths[1], fx.archives.nodeSha, posix.dirname(posix.dirname(connectionNode)), fx.archives.nodeVersion, ACK]);
     assert.equal(JSON.parse(readFileSync(boot.receipt, "utf8")).connection_node, connectionNode);
     assert.deepEqual(Object.keys(model.load(fx.state).hosts), []);
+    // A new confirmation cannot reset an interrupted bootstrap's machine/root guard.
+    fx.confirm(host); writeConn(fx.tmp, host);
+    const retryArgs = ["bootstrap-node", "--state", fx.state, "--host-id", host.host_id, "--connection-file", conn, "--apply", "--account", "ops", "--host-root", fx.target, "--ack", ACK,
+      "--volta-archive", fx.archives.voltaTar, "--node-archive", fx.archives.nodeTar];
+    const blockedRetry = captureMain(retryArgs); assert.equal(blockedRetry.code, 2); assert.match(blockedRetry.stderr, /already started/);
+    assert.equal(mock.log.filter(e => e.cmd === "scp").length, 2);
+    const recovered = captureMain([...retryArgs, "--recover-ack", "I-VERIFIED-BOOTSTRAP-IS-STOPPED", "--recovery-statement", "Fixture only: the simulated old process is stopped; retry exactly the same pinned inputs"]);
+    assert.equal(recovered.code, 0, recovered.stderr);
+    assert.ok(readdirSync(join(fx.state, "hosts", host.host_id, "bootstrap")).some(n => n.startsWith("recovery-")));
     mock.restore();
     host.connection.node = connectionNode;
     const enrollFile = join(fx.tmp, "register.json"); writeFileSync(enrollFile, JSON.stringify({ hosts: [host], projects: [] }));
@@ -355,6 +370,18 @@ test("bootstrap-node apply without ack blocked", () => {
   } finally { mock.restore(); fx.cleanup(); }
 });
 
+test("bootstrap with valid archives but no root confirmation cannot write or upload", () => {
+  const fx = cliFixture(), mock = mockTransport({ probeJson: missingProbe });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" }), conn = writeConn(fx.tmp, host);
+    const r = captureMain(["bootstrap-node", "--state", fx.state, "--host-id", host.host_id, "--connection-file", conn, "--apply", "--account", "ops", "--host-root", fx.target, "--ack", ACK,
+      "--volta-archive", fx.archives.voltaTar, "--node-archive", fx.archives.nodeTar]);
+    assert.equal(r.code, 2); assert.match(r.stderr, /root-confirm/);
+    assert.equal(mock.log.filter(e => e.cmd === "scp").length, 0);
+    assert.ok(mock.log.every(e => e.args.at(-1).includes("--probe")));
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
 test("bootstrap-node sha mismatch blocked", () => {
   const fx = cliFixture();
   const mock = mockTransport({ probeJson: missingProbe });
@@ -428,6 +455,7 @@ test("bootstrap-node apply then enroll writes inventory and status", linuxExecut
   const mock = mockTransport({ probeJson: missingProbe });
   try {
     const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    fx.confirm(host);
     const conn = writeConn(fx.tmp, host);
     const applied = captureMain([
       "bootstrap-node", "--state", fx.state, "--host-id", "wsl-a",
@@ -518,7 +546,7 @@ test("environmentSpec uses managed volta path", () => {
     host_id: "node-a", display_name: "Node A", platform: process.platform === "win32" ? "windows" : "linux",
     transport: "local", root: target, identity: agent.fingerprint(), connection: {},
   };
-  model.register(state, { hosts: [host], projects: [] });
+  const legacy = model.load(state); legacy.hosts[host.host_id] = host; model.save(state, legacy); // existing runtime, no fabricated confirmation
   const prev = recipes.hostRecipesHooks.call;
   const voltaBin = core.targetJoin(host, "_host/toolchains/ops/volta/bin/volta");
   recipes.hostRecipesHooks.call = (_h, req) => {
@@ -554,7 +582,7 @@ test("environmentSpec still throws when volta truly absent", () => {
     host_id: "node-a", display_name: "Node A", platform: process.platform === "win32" ? "windows" : "linux",
     transport: "local", root: target, identity: agent.fingerprint(), connection: {},
   };
-  model.register(state, { hosts: [host], projects: [] });
+  const legacy = model.load(state); legacy.hosts[host.host_id] = host; model.save(state, legacy); // existing runtime, no fabricated confirmation
   const prev = recipes.hostRecipesHooks.call;
   recipes.hostRecipesHooks.call = (_h, req) => {
     if (req.action === "snapshot") return { paths: { [req.paths[0]]: { kind: "absent" } } };