@namewta/speculo 1.0.17 → 1.0.18

package/template/workflows/ops/common/tools/opslib/workspace.mjs

@@ -0,0 +1,107 @@
+/** Explicit controller/server/project routing and bounded workspace paths. */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative as pathRelative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { digest, exact, identifier, noSymlinks, OpsError, readJson } from "./core.mjs";
+
+export const WORKS = Object.freeze({
+  controller: "I-initialize", access: "S-server-connect", server: "H-host-manage",
+  project: "D-project-deploy", inventory: "V-inventory-view",
+});
+const WORKFLOW = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+export const MAX_JSON_BYTES = 16 * 1024 * 1024;
+
+export function statePath(value) {
+  if (typeof value !== "string" || !isAbsolute(value) || value.includes("\0") || value.split(/[\\/]/).includes("..")) {
+    throw new OpsError("--state must be an explicit absolute path without traversal; never inferred from cwd");
+  }
+  const state = resolve(value);
+  const rel = pathRelative(WORKFLOW, state);
+  if (dirname(state) === state || rel === "" || (rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel))) {
+    throw new OpsError("state must be a dedicated runtime directory outside static workflow assets");
+  }
+  noSymlinks(state, { allowMissing: false });
+  if (!statSync(state).isDirectory()) throw new OpsError("state is not a directory");
+  return state;
+}
+
+export function readBoundedJson(path) {
+  noSymlinks(path, { allowMissing: false });
+  const st = statSync(path);
+  if (!st.isFile() || st.size > MAX_JSON_BYTES) throw new OpsError("JSON file is not regular or exceeds 16 MiB");
+  return readJson(path);
+}
+
+export function readRegistry(state) {
+  statePath(state);
+  const value = readBoundedJson(join(state, "status.json"));
+  if (value.schema_version !== 3 || value.workflow !== "ops" || !Number.isSafeInteger(value.revision) || value.revision < 0) {
+    throw new OpsError("workspace requires OPS status schema v3; legacy state must be imported, not overwritten");
+  }
+  if (!value.controller || !value.controller.controller_id) throw new OpsError("initialize the controller first");
+  identifier(value.controller.controller_id, "controller_id");
+  if (typeof value.controller.state_root !== "string" || resolve(value.controller.state_root) !== resolve(state)) throw new OpsError("controller state_root mismatch; do not silently adopt another workspace");
+  for (const key of ["hosts", "projects", "deployments", "bindings", "allocations", "releases"]) {
+    if (!value[key] || typeof value[key] !== "object" || Array.isArray(value[key])) throw new OpsError(`invalid registry map: ${key}`);
+    if (Object.keys(value[key]).length > 10000) throw new OpsError(`registry map exceeds workspace bound: ${key}`);
+    for (const id of Object.keys(value[key])) identifier(id, key);
+  }
+  for (const [id, h] of Object.entries(value.hosts)) {
+    if (!h || h.host_id !== id || !["local", "ssh"].includes(h.transport)) throw new OpsError(`invalid host record: ${id}`);
+  }
+  for (const [id, p] of Object.entries(value.projects)) {
+    if (!p || p.project_id !== id) throw new OpsError(`invalid project record: ${id}`);
+  }
+  for (const [id, d] of Object.entries(value.deployments)) {
+    if (!d || d.deployment_id !== id || !Object.hasOwn(value.hosts, d.host_id) || !Object.hasOwn(value.projects, d.project_id)) {
+      throw new OpsError(`orphan or invalid deployment: ${id}`);
+    }
+  }
+  return value;
+}
+
+export function ids(value, label) {
+  if (!Array.isArray(value) || new Set(value).size !== value.length) throw new OpsError(`${label} must be an array of distinct IDs`);
+  return value.map((id) => identifier(id, label));
+}
+
+export function route(registry, context) {
+  exact(context, new Set(["scope", "server_ids", "project_ids"]), new Set(["scope", "server_ids", "project_ids"]), "context");
+  if (!Object.hasOwn(WORKS, context.scope)) throw new OpsError("scope must be controller, access, server, project or inventory");
+  const servers = ids(context.server_ids, "server_ids");
+  const projects = ids(context.project_ids, "project_ids");
+  if (context.scope === "controller" && (servers.length || projects.length)) throw new OpsError("controller scope cannot target a server or project; use S/H/D");
+  if (["access", "server"].includes(context.scope) && (servers.length !== 1 || projects.length)) throw new OpsError("S/H require exactly one explicit server and no project");
+  if (context.scope === "project" && (!servers.length || projects.length !== 1)) throw new OpsError("D requires explicit server(s) and exactly one project; no last-used/cwd fallback");
+  for (const id of servers) if (context.scope !== "access" && !Object.hasOwn(registry.hosts, id)) throw new OpsError(`unknown server: ${id}; enroll via S first`);
+  for (const id of projects) if (!Object.hasOwn(registry.projects, id)) throw new OpsError(`unknown project: ${id}; explicitly register the project first`);
+  return { scope: context.scope, work: WORKS[context.scope], controller_id: registry.controller.controller_id,
+    server_ids: servers, project_ids: projects, host_ids: servers, registration_required: servers.filter((id) => !Object.hasOwn(registry.hosts, id)), note: "server maps to Host.host_id; controller is never an implicit local server" };
+}
+
+export function catalogUnlocked(state) {
+  noSymlinks(join(state, ".locks", "catalog"));
+  if (existsSync(join(state, ".locks", "catalog"))) throw new OpsError("catalog lock held; inspect the owner before generating a new snapshot");
+}
+
+export function fileDigest(path) {
+  noSymlinks(path, { allowMissing: false });
+  if (!statSync(path).isFile() || statSync(path).size > MAX_JSON_BYTES) throw new OpsError("file exceeds snapshot bound");
+  return digest(readFileSync(path));
+}
+
+/** Pin identity and transport, not changeable host_services annotations. */
+export function targetDigest(host) {
+  if (!host) throw new OpsError("missing target host");
+  const { host_id, root, identity, platform, transport, connection } = host;
+  const known_hosts_digest = transport === "ssh" ? fileDigest(connection.known_hosts) : null;
+  return digest({ host_id, root, identity, platform, transport, connection, known_hosts_digest });
+}
+
+export function containedPath(root, path) {
+  if (typeof path !== "string" || !isAbsolute(path) || path.split(/[\\/]/).includes("..")) throw new OpsError("expected an absolute contained artifact path");
+  const rel = pathRelative(resolve(root), resolve(path));
+  if (!rel || rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) throw new OpsError("artifact path outside workspace");
+  noSymlinks(path, { allowMissing: false });
+  return resolve(path);
+}

package/template/workflows/ops/common/tools/opslib/workspace_cli.mjs

@@ -0,0 +1,80 @@
+/** Additive workspace commands. Legacy CLI semantics remain owned by cli.mjs. */
+import { isAbsolute } from "node:path";
+import { OpsError } from "./core.mjs";
+import { readBoundedJson, readRegistry, route, statePath } from "./workspace.mjs";
+import { checkServer } from "./server_checks.mjs";
+import { generateFleet } from "./fleet.mjs";
+import { authorizeTask, prepareTask, runTask } from "./tasks.mjs";
+
+export const COMMANDS = Object.freeze(["workspace-help", "route", "server-check", "fleet", "task-plan", "task-authorize", "task-run"]);
+const options = {
+  route: ["scope", "server", "project"],
+  "server-check": ["server", "profile", "min-free-mib", "min-memory-mib"],
+  fleet: ["stale-hours"], "task-plan": ["file"],
+  "task-authorize": ["task", "digest", "by", "statement", "ack-destructive"], "task-run": ["task"], "workspace-help": [],
+};
+export function workspaceCommand(argv) {
+  const rest = [...argv];
+  for (let i = rest.length - 1; i >= 0; i--) if (rest[i] === "--state") rest.splice(i, 2);
+  return COMMANDS.includes(rest[0]) ? rest[0] : null;
+}
+export function parseWorkspaceArgs(argv) {
+  const command = workspaceCommand(argv);
+  if (!command) throw new OpsError("unknown workspace command");
+  const args = [...argv], out = { command };
+  args.splice(args.indexOf(command), 1);
+  const allowed = new Set(["state", ...options[command]]);
+  while (args.length) {
+    const flag = args.shift();
+    if (!flag.startsWith("--") || !allowed.has(flag.slice(2))) throw new OpsError(`unknown ${command} argument: ${flag}`);
+    const key = flag.slice(2);
+    if (Object.hasOwn(out, key)) throw new OpsError(`duplicate argument: ${flag}`);
+    const value = args.shift();
+    if (!value || value.startsWith("--")) throw new OpsError(`${flag} needs a value`);
+    out[key] = value;
+  }
+  if (command !== "workspace-help" && !out.state) throw new OpsError("--state is required and must be absolute");
+  return out;
+}
+const required = (args, key) => { if (!args[key]) throw new OpsError(`--${key} is required`); return args[key]; };
+const list = (v) => v ? v.split(",") : [];
+function integer(value, fallback) {
+  if (value === undefined) return fallback;
+  if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(Number(value))) throw new OpsError("threshold must be a positive integer");
+  return Number(value);
+}
+export async function main(argv = process.argv.slice(2)) {
+  try {
+    const args = parseWorkspaceArgs(argv);
+    if (args.command === "workspace-help") {
+      process.stdout.write(JSON.stringify({ commands: options, usage: "node ops.mjs --state ABSOLUTE_STATE COMMAND [options]",
+        workflow: "I controller; S server access; H server baseline; D project deployment; V local inventory",
+        task: "task-plan -> record existing explicit user authorization once via task-authorize -> task-run; no per-step reconfirmation; no automatic retry",
+        legacy: "All other commands retain the original plan/approve/apply contracts" }, null, 2) + "\n");
+      return 0;
+    }
+    const state = statePath(args.state);
+    // Keep the existing complete schema/semantic validator authoritative in the installed runtime.
+    const { load } = await import("./model.mjs");
+    load(state);
+    let result;
+    switch (args.command) {
+      case "route": result = route(readRegistry(state), { scope: required(args, "scope"), server_ids: list(args.server), project_ids: list(args.project) }); break;
+      case "server-check": result = await checkServer(state, required(args, "server"), { profile: args.profile ?? "base",
+        minFreeMiB: integer(args["min-free-mib"], 1024), minMemoryMiB: integer(args["min-memory-mib"], 256) }); break;
+      case "fleet": result = generateFleet(state, { staleHours: integer(args["stale-hours"], 24) }); break;
+      case "task-plan": {
+        const file = required(args, "file");
+        if (!isAbsolute(file)) throw new OpsError("--file must be an absolute task request path");
+        result = await prepareTask(state, readBoundedJson(file)); break;
+      }
+      case "task-authorize": result = authorizeTask(state, required(args, "task"), required(args, "digest"), required(args, "by"), required(args, "statement"), args["ack-destructive"] ?? null); break;
+      case "task-run": result = await runTask(state, required(args, "task")); break;
+    }
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    return ["blocked", "failed", "partial", "unknown", "stale", "docs_pending", "interrupted"].includes(result.status) ? 2 : 0;
+  } catch (error) {
+    process.stderr.write(JSON.stringify({ status: "blocked", error: error.message || String(error) }) + "\n");
+    return 2;
+  }
+}

package/template/workflows/ops/common/tools/validate-ops.mjs

@@ -5,10 +5,10 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { validateStatus } from "./opslib/model.mjs";
+import { WORKS } from "./opslib/workspace.mjs";
 
 const tools = dirname(fileURLToPath(import.meta.url));
 const root = resolve(tools, "../..");
-const expected = ["D-project-deploy", "H-host-manage", "I-initialize"];
 const args = process.argv.slice(2);
 
 try {
@@ -16,12 +16,17 @@ try {
     const works = readdirSync(root, { withFileTypes: true })
       .filter((x) => x.isDirectory() && !["common", "_state", "__pycache__"].includes(x.name))
       .map((x) => x.name).sort();
-    if (JSON.stringify(works) !== JSON.stringify(expected)) throw new Error("OPS must expose exactly three work directories");
+    const expected = Object.values(WORKS).sort();
+    if (JSON.stringify(works) !== JSON.stringify(expected)) throw new Error("OPS Work directories differ from explicit scope router");
+    const manifest = JSON.parse(readFileSync(join(root, "manifest.json"), "utf8"));
+    const stages = manifest.stages.map((s) => s.id).sort();
+    if (new Set(stages).size !== stages.length || JSON.stringify(stages) !== JSON.stringify(works.map((w) => w.slice(2)).sort())) throw new Error("manifest stages differ from Work entries");
+    for (const stage of manifest.stages) for (const id of stage.after) if (!stages.includes(id)) throw new Error("unknown manifest prerequisite " + id);
     for (const id of works) {
       const text = readFileSync(join(root, id, id + ".md"), "utf8");
-      if (!text.includes("type: workflow-entry") || !text.includes("读取范围")) throw new Error("invalid work " + id);
+      if (!text.includes("type: workflow-entry") || !text.includes("读取范围") || !text.includes("id: ops/" + id.slice(2))) throw new Error("invalid work " + id);
     }
-    for (const file of ["INDEX.md", "README.md", "manifest.json", "runtime-contract.json", "common/USAGE.md", "common/CAPABILITIES.md", "common/tools/opslib/execution.mjs"]) {
+    for (const file of ["INDEX.md", "README.md", "manifest.json", "runtime-contract.json", "common/USAGE.md", "common/WORKSPACE-USAGE.md", "common/CAPABILITIES.md", "common/templates/FLEET.html", "common/schemas/fleet-view.schema.json", "common/schemas/task-request.schema.json", "common/schemas/server-check.schema.json", "common/tools/opslib/execution.mjs", "common/tools/opslib/tasks.mjs", "common/tools/opslib/fleet.mjs"]) {
       if (!existsSync(join(root, file))) throw new Error("missing " + file);
     }
     for (const name of readdirSync(join(root, "common/schemas")).filter((x) => x.endsWith(".json"))) {
@@ -30,10 +35,8 @@ try {
     JSON.parse(readFileSync(join(root, "common/toolchains/volta-linux.json"), "utf8"));
     validateStatus(JSON.parse(readFileSync(join(root, "_state/status.json"), "utf8")));
     console.log("resource schema valid");
-    console.log(JSON.stringify({
-      valid: true, version: "2.2.0", workers: works, schema_version: 3,
-      scope: "static and empty-resource-schema check; not live target acceptance",
-    }, null, 2));
+    console.log(JSON.stringify({ valid: true, version: manifest.version, workers: works, schema_version: 3,
+      scope: "static and empty-resource-schema check; not live target acceptance" }, null, 2));
   } else if (args.length === 2 && ["--state-root", "--state"].includes(args[0])) {
     const p = spawnSync(process.execPath, [join(tools, "ops.mjs"), "--state", resolve(args[1]), "validate"], { encoding: "utf8", timeout: 30000 });
     if (p.status !== 0) throw new Error(p.stdout + p.stderr);

package/template/workflows/ops/manifest.json

@@ -22,31 +22,50 @@
       "risk": "local-reversible",
       "context_budget": 16000
     },
+    {
+      "id": "server-connect",
+      "after": [
+        "initialize"
+      ],
+      "inputs": [
+        "server",
+        "verified-host-key",
+        "key-or-agent"
+      ],
+      "outputs": [
+        "server-registration",
+        "inventory",
+        "server-checks"
+      ],
+      "risk": "production-critical",
+      "context_budget": 20000
+    },
     {
       "id": "host-manage",
       "after": [],
       "inputs": [
-        "host",
+        "server",
         "spec",
-        "approval"
+        "task-authorization-or-plan-approval"
       ],
       "outputs": [
         "host-run",
         "verification",
-        "dual-documents"
+        "dual-documents",
+        "server-checks"
       ],
       "risk": "production-critical",
-      "context_budget": 22000
+      "context_budget": 24000
     },
     {
       "id": "project-deploy",
       "after": [],
       "inputs": [
         "project",
-        "hosts",
+        "explicit-servers",
         "bindings",
         "spec",
-        "approval"
+        "task-authorization-or-plan-approval"
       ],
       "outputs": [
         "release",
@@ -54,7 +73,24 @@
         "dual-documents"
       ],
       "risk": "production-critical",
-      "context_budget": 28000
+      "context_budget": 30000
+    },
+    {
+      "id": "inventory-view",
+      "after": [],
+      "inputs": [
+        "resource-state",
+        "server-checks",
+        "task-summaries"
+      ],
+      "outputs": [
+        "fleet-markdown",
+        "fleet-json",
+        "fleet-html",
+        "view-receipt"
+      ],
+      "risk": "local-reversible",
+      "context_budget": 16000
     }
   ]
 }