cueline 0.2.1 → 0.3.0

package/schemas/cli-run-export.schema.json

@@ -0,0 +1,410 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cueline.dev/schemas/cli-run-export.schema.json",
+  "title": "cueline run export --json output (support bundle)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "protocol",
+    "version",
+    "generatedAt",
+    "runId",
+    "status",
+    "verification",
+    "diagnosis",
+    "timeline"
+  ],
+  "properties": {
+    "schema": { "const": "cueline-run-export/1" },
+    "protocol": { "const": "cueline-run-bundle/0.1" },
+    "version": { "type": "string", "minLength": 1 },
+    "generatedAt": { "$ref": "#/$defs/isoTimestamp" },
+    "runId": { "type": "string", "minLength": 1 },
+    "status": { "$ref": "#/$defs/status" },
+    "verification": { "$ref": "#/$defs/verification" },
+    "diagnosis": { "$ref": "#/$defs/diagnosis" },
+    "timeline": { "$ref": "#/$defs/timeline" }
+  },
+  "$defs": {
+    "isoTimestamp": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
+    },
+    "status": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runId",
+        "status",
+        "executor",
+        "allowProcessExecution",
+        "phase",
+        "round",
+        "maxRounds",
+        "lastEventSequence",
+        "runtime",
+        "cancellation",
+        "controller",
+        "jobs",
+        "continueAllowed",
+        "safeNextAction"
+      ],
+      "properties": {
+        "runId": { "type": "string", "minLength": 1 },
+        "status": {
+          "enum": ["running", "complete", "blocked", "cancelled", "failed"]
+        },
+        "executor": { "enum": ["caller", "process"] },
+        "allowProcessExecution": { "type": "boolean" },
+        "phase": { "type": "string", "minLength": 1 },
+        "round": { "type": "integer", "minimum": 0 },
+        "maxRounds": { "type": "integer", "minimum": 0 },
+        "lastEventSequence": { "type": "integer", "minimum": 0 },
+        "runtime": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["ownership"],
+          "properties": {
+            "ownership": {
+              "enum": ["missing", "active", "stale", "released", "invalid"]
+            },
+            "heartbeatAt": { "type": "string", "minLength": 1 },
+            "ageMs": { "type": "number", "minimum": 0 },
+            "pid": { "anyOf": [{ "type": "string" }, { "type": "number" }] }
+          }
+        },
+        "cancellation": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["runRequested", "jobRequests"],
+          "properties": {
+            "runRequested": { "type": "boolean" },
+            "jobRequests": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "controller": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "pendingTurns",
+            "acceptedCommands",
+            "responseAccepted",
+            "lastAcceptedAction",
+            "lastAcceptedRequestId",
+            "lastAcceptedJobKeys"
+          ],
+          "properties": {
+            "pendingTurns": { "type": "integer", "minimum": 0 },
+            "acceptedCommands": { "type": "integer", "minimum": 0 },
+            "responseAccepted": { "type": "boolean" },
+            "lastAcceptedAction": {
+              "enum": ["dispatch", "wait", "inspect", "complete", "blocked", null]
+            },
+            "lastAcceptedRequestId": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
+            "lastAcceptedJobKeys": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "reconciliation": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "requiredReason",
+                "operatorConfirmation",
+                "abandonedRequestId",
+                "retryRequestId",
+                "promptHash",
+                "resendBlockedReason"
+              ],
+              "properties": {
+                "requiredReason": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
+                "operatorConfirmation": {
+                  "enum": ["not_sent_confirmed", "manual_send_confirmed", null]
+                },
+                "abandonedRequestId": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
+                "retryRequestId": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
+                "promptHash": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
+                "resendBlockedReason": { "anyOf": [{ "type": "string" }, { "type": "null" }] }
+              }
+            },
+            "archive": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["enabled", "status", "code", "proof"],
+              "properties": {
+                "enabled": { "const": true },
+                "status": { "type": "string", "minLength": 1 },
+                "code": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
+                "proof": {}
+              }
+            }
+          }
+        },
+        "jobs": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["total", "counts", "items"],
+          "properties": {
+            "total": { "type": "integer", "minimum": 0 },
+            "counts": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "pending",
+                "running",
+                "succeeded",
+                "failed",
+                "timed_out",
+                "cancelled",
+                "ambiguous",
+                "orphaned"
+              ],
+              "properties": {
+                "pending": { "type": "integer", "minimum": 0 },
+                "running": { "type": "integer", "minimum": 0 },
+                "succeeded": { "type": "integer", "minimum": 0 },
+                "failed": { "type": "integer", "minimum": 0 },
+                "timed_out": { "type": "integer", "minimum": 0 },
+                "cancelled": { "type": "integer", "minimum": 0 },
+                "ambiguous": { "type": "integer", "minimum": 0 },
+                "orphaned": { "type": "integer", "minimum": 0 }
+              }
+            },
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "jobId",
+                  "jobKey",
+                  "required",
+                  "lane",
+                  "mode",
+                  "status",
+                  "persistedStatus"
+                ],
+                "properties": {
+                  "jobId": { "type": "string", "minLength": 1 },
+                  "jobKey": { "type": "string", "minLength": 1 },
+                  "required": { "type": "boolean" },
+                  "lane": { "type": "string", "minLength": 1 },
+                  "mode": { "enum": ["advise", "work"] },
+                  "status": {
+                    "enum": [
+                      "pending",
+                      "running",
+                      "succeeded",
+                      "failed",
+                      "timed_out",
+                      "cancelled",
+                      "ambiguous",
+                      "orphaned"
+                    ]
+                  },
+                  "persistedStatus": { "type": "string", "minLength": 1 },
+                  "workClaim": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["claimed"],
+                    "properties": {
+                      "claimed": { "type": "boolean" },
+                      "claimedAt": { "type": "string", "minLength": 1 },
+                      "heartbeatAt": { "type": "string", "minLength": 1 },
+                      "expiresAt": { "type": "string", "minLength": 1 },
+                      "startedAt": { "type": "string", "minLength": 1 }
+                    }
+                  },
+                  "execution": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "runnerId": { "type": "string", "minLength": 1 },
+                      "pid": { "type": "number" },
+                      "model": { "type": "string", "minLength": 1 },
+                      "provider": { "type": "string", "minLength": 1 },
+                      "phase": { "type": "string", "minLength": 1 },
+                      "lastProgressAt": { "type": "string", "minLength": 1 }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "continueAllowed": { "type": "boolean" },
+        "safeNextAction": { "type": "string", "minLength": 1 }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runId",
+        "outcome",
+        "marker",
+        "eventLog",
+        "snapshot",
+        "runtimeOwnership",
+        "findings"
+      ],
+      "properties": {
+        "runId": { "type": "string", "minLength": 1 },
+        "outcome": { "enum": ["verified", "degraded", "unreadable"] },
+        "marker": { "enum": ["valid", "missing", "invalid"] },
+        "eventLog": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "readable",
+            "totalEvents",
+            "authoritativeEvents",
+            "lastSequence"
+          ],
+          "properties": {
+            "readable": { "type": "boolean" },
+            "totalEvents": { "type": "integer", "minimum": 0 },
+            "authoritativeEvents": { "type": "integer", "minimum": 0 },
+            "lastSequence": { "anyOf": [{ "type": "integer" }, { "type": "null" }] }
+          }
+        },
+        "snapshot": { "enum": ["missing", "valid", "stale", "invalid"] },
+        "runtimeOwnership": {
+          "enum": ["missing", "active", "stale", "released", "invalid"]
+        },
+        "findings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["code", "severity", "surface", "message"],
+            "properties": {
+              "code": { "type": "string", "minLength": 1 },
+              "severity": { "enum": ["warning", "error"] },
+              "surface": {
+                "enum": ["marker", "events", "snapshot", "runtime", "jobs"]
+              },
+              "message": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "diagnosis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runId",
+        "outcome",
+        "phase",
+        "summary",
+        "nextAction",
+        "eventSequence",
+        "findings"
+      ],
+      "properties": {
+        "runId": { "type": "string", "minLength": 1 },
+        "outcome": { "enum": ["healthy", "action_required", "blocked"] },
+        "phase": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 },
+        "nextAction": { "type": "string", "minLength": 1 },
+        "eventSequence": { "type": "integer", "minimum": 0 },
+        "findings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["code", "severity", "message", "action", "evidence"],
+            "properties": {
+              "code": { "type": "string", "minLength": 1 },
+              "severity": { "enum": ["info", "warning", "error"] },
+              "message": { "type": "string", "minLength": 1 },
+              "action": { "type": "string", "minLength": 1 },
+              "evidence": {
+                "type": "object",
+                "additionalProperties": {
+                  "anyOf": [
+                    { "type": "string" },
+                    { "type": "number" },
+                    { "type": "boolean" },
+                    { "type": "null" }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "timeline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "runId",
+        "sourceEventsPath",
+        "afterSequence",
+        "limit",
+        "totalEvents",
+        "latestSequence",
+        "returnedEvents",
+        "hasMore",
+        "nextAfterSequence",
+        "entries"
+      ],
+      "properties": {
+        "schema": { "const": "cueline-timeline/0.1" },
+        "runId": { "type": "string", "minLength": 1 },
+        "sourceEventsPath": { "type": "string", "minLength": 1 },
+        "afterSequence": { "type": "integer", "minimum": 0 },
+        "limit": { "type": "integer", "minimum": 1 },
+        "totalEvents": { "type": "integer", "minimum": 0 },
+        "latestSequence": { "type": "integer", "minimum": 0 },
+        "returnedEvents": { "type": "integer", "minimum": 0 },
+        "hasMore": { "type": "boolean" },
+        "nextAfterSequence": { "type": "integer", "minimum": 0 },
+        "entries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "sequence",
+              "timestamp",
+              "type",
+              "category",
+              "summary",
+              "attributes",
+              "payloadHash"
+            ],
+            "properties": {
+              "sequence": { "type": "integer", "minimum": 1 },
+              "timestamp": {
+                "anyOf": [{ "$ref": "#/$defs/isoTimestamp" }, { "type": "null" }]
+              },
+              "type": { "type": "string", "minLength": 1 },
+              "category": { "type": "string", "minLength": 1 },
+              "summary": { "type": "string" },
+              "attributes": {
+                "type": "object",
+                "additionalProperties": {
+                  "anyOf": [
+                    { "type": "string" },
+                    { "type": "number" },
+                    { "type": "boolean" }
+                  ]
+                }
+              },
+              "payloadHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+              "ownerFingerprint": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/cli-runs-prune.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cueline.dev/schemas/cli-runs-prune.schema.json",
+  "title": "cueline runs prune --json output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "version",
+    "home",
+    "apply",
+    "olderThanMs",
+    "cutoff",
+    "states",
+    "decisions",
+    "prunedRuns",
+    "eligibleRuns",
+    "keptRuns",
+    "removedJobRecords",
+    "errors"
+  ],
+  "properties": {
+    "schema": { "const": "cueline-runs-prune/1" },
+    "version": { "type": "string", "minLength": 1 },
+    "home": { "type": "string", "minLength": 1 },
+    "apply": { "type": "boolean" },
+    "olderThanMs": { "type": "integer", "minimum": 0 },
+    "cutoff": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
+    },
+    "states": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "enum": ["complete", "blocked", "cancelled"] }
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["runId", "decision"],
+        "allOf": [
+          {
+            "if": {
+              "properties": { "decision": { "const": "kept" } },
+              "required": ["decision"]
+            },
+            "then": { "required": ["reason"], "properties": { "reason": {} } },
+            "else": { "not": { "required": ["reason"], "properties": { "reason": {} } } }
+          }
+        ],
+        "properties": {
+          "runId": { "type": "string", "minLength": 1 },
+          "decision": { "enum": ["pruned", "eligible", "kept"] },
+          "reason": {
+            "enum": [
+              "unreadable",
+              "non_terminal",
+              "state_excluded",
+              "runtime_active",
+              "active_jobs",
+              "too_recent",
+              "delete_failed"
+            ]
+          },
+          "status": { "type": "string", "minLength": 1 },
+          "lastEventAt": {
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
+          }
+        }
+      }
+    },
+    "prunedRuns": { "type": "integer", "minimum": 0 },
+    "eligibleRuns": { "type": "integer", "minimum": 0 },
+    "keptRuns": { "type": "integer", "minimum": 0 },
+    "removedJobRecords": { "type": "integer", "minimum": 0 },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["runId", "message"],
+        "properties": {
+          "runId": { "type": "string", "minLength": 1 },
+          "message": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/scripts/artifact-integrity.mjs

@@ -0,0 +1,114 @@
+import { createHash } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const execFile = promisify(execFileCallback);
+const SCHEMA = "cueline-artifact-manifest/1";
+
+export async function sha256File(file) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(file)) hash.update(chunk);
+  return hash.digest("hex");
+}
+
+function isInside(parent, candidate) {
+  return candidate.startsWith(`${parent}${path.sep}`);
+}
+
+export async function prepareOutputDirectory(root, requested = "release-artifacts") {
+  const rootReal = await realpath(root);
+  const output = path.resolve(rootReal, requested);
+  if (!isInside(rootReal, output)) {
+    throw new Error("artifact output must be a child directory of the repository");
+  }
+  await mkdir(output, { recursive: true });
+  if ((await lstat(output)).isSymbolicLink()) {
+    throw new Error("artifact output directory must not be a symbolic link");
+  }
+  const outputReal = await realpath(output);
+  if (!isInside(rootReal, outputReal)) {
+    throw new Error("artifact output resolved outside the repository");
+  }
+  return outputReal;
+}
+
+function safeArtifactName(value) {
+  return typeof value === "string" && value !== "" && value === path.basename(value) && !value.includes("..") && value.endsWith(".tgz");
+}
+
+export async function verifyArtifactManifest(manifestPath) {
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  if (manifest.schema !== SCHEMA) throw new Error("unsupported artifact manifest schema");
+  if (!safeArtifactName(manifest.artifact?.filename)) throw new Error("unsafe artifact filename");
+  if (!/^[0-9a-f]{64}$/.test(manifest.artifact.sha256)) throw new Error("invalid artifact sha256");
+  const directory = path.dirname(manifestPath);
+  const artifactPath = path.join(directory, manifest.artifact.filename);
+  const checksumPath = `${artifactPath}.sha256`;
+  const actual = await sha256File(artifactPath);
+  if (actual !== manifest.artifact.sha256) throw new Error("artifact sha256 mismatch");
+  const checksum = await readFile(checksumPath, "utf8");
+  if (checksum !== `${actual}  ${manifest.artifact.filename}\n`) throw new Error("checksum file mismatch");
+  const size = (await lstat(artifactPath)).size;
+  if (size !== manifest.artifact.size) throw new Error("artifact size mismatch");
+  return { schema: SCHEMA, status: "ok", filename: manifest.artifact.filename, sha256: actual, size };
+}
+
+export async function buildArtifact(root, requestedOutput = "release-artifacts") {
+  const output = await prepareOutputDirectory(root, requestedOutput);
+  const { stdout } = await execFile("npm", ["pack", "--json", "--pack-destination", output], {
+    cwd: root,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  const report = JSON.parse(stdout)[0];
+  if (!safeArtifactName(report?.filename)) throw new Error("npm pack returned an unsafe filename");
+  const artifactPath = path.join(output, report.filename);
+  const sha256 = await sha256File(artifactPath);
+  const files = [...(report.files ?? [])]
+    .map(({ path: file, size, mode }) => ({ path: file, size, mode }))
+    .sort((left, right) => left.path.localeCompare(right.path));
+  const manifest = {
+    schema: SCHEMA,
+    package: { name: report.name, version: report.version },
+    artifact: {
+      filename: report.filename,
+      sha256,
+      npmShasum: report.shasum,
+      npmIntegrity: report.integrity,
+      size: report.size,
+      unpackedSize: report.unpackedSize,
+      fileCount: files.length,
+    },
+    files,
+  };
+  const manifestPath = `${artifactPath}.manifest.json`;
+  await writeFile(`${artifactPath}.sha256`, `${sha256}  ${report.filename}\n`, { mode: 0o600 });
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  const verification = await verifyArtifactManifest(manifestPath);
+  return { ...verification, manifestPath, checksumPath: `${artifactPath}.sha256`, fileCount: files.length };
+}
+
+function parseArguments(args) {
+  const [command, value] = args;
+  if (command === "build" && args.length <= 2) return { command, output: value ?? "release-artifacts" };
+  if (command === "verify" && args.length === 2) return { command, manifest: value };
+  throw new Error("usage: artifact-integrity.mjs build [output-directory] | verify <manifest-path>");
+}
+
+const invokedPath = process.argv[1] === undefined ? "" : path.resolve(process.argv[1]);
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  try {
+    const root = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+    const args = parseArguments(process.argv.slice(2));
+    const report = args.command === "build"
+      ? await buildArtifact(root, args.output)
+      : await verifyArtifactManifest(path.resolve(root, args.manifest));
+    console.log(JSON.stringify(report, null, 2));
+  } catch (error) {
+    console.error(JSON.stringify({ schema: SCHEMA, status: "error", message: error instanceof Error ? error.message : "artifact operation failed" }));
+    process.exitCode = 1;
+  }
+}