@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-runbook/reference/dex-template.runbook.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://stravica.ai/schemas/runbook/1.0",
+  "id": "dex-template-v1-to-v2",
+  "target": "dex",
+  "description": "Template runbook for Dex cutover. Parameterise {{daveRoot}} from inspection output before executing.",
+  "version": "1.0.0",
+  "inspectionRef": "inspection-dex.json",
+  "steps": [
+    {
+      "id": "step-1",
+      "intent": "snapshot-v1-fork",
+      "description": "Preserve v1 fork.",
+      "params": { "snapshotSuffix": "pre-v2-{{inspectedAt|date}}" },
+      "preconditions": [
+        { "assert": "workingTreeClean" },
+        { "assert": "onBranch", "value": "main" }
+      ],
+      "expect": { "produces": ["{{daveRoot}}-pre-v2-{{inspectedAt|date}}/"] },
+      "rollback": { "trigger": "v2 instance fails 24h soak", "action": "restore-from-snapshot" }
+    },
+    {
+      "id": "step-2",
+      "intent": "run-migrate-to-v2",
+      "description": "Run migrate-to-v2 CLI.",
+      "params": {
+        "source": "{{daveRoot}}",
+        "target": "{{daveRoot}}-v2",
+        "dryRun": false
+      },
+      "preconditions": [
+        { "assert": "snapshotExists" },
+        { "assert": "nodeVersion", "value": ">=24" },
+        { "assert": "pnpmOnPath" }
+      ],
+      "expect": { "produces": ["{{daveRoot}}-v2/package.json", "{{daveRoot}}-v2/operator/"] },
+      "rollback": { "trigger": "migrate-to-v2 exits non-zero", "action": "restore-from-snapshot" }
+    },
+    {
+      "id": "step-3",
+      "intent": "update-host-service",
+      "description": "Update the workspace launchd plist to point to the v2 instance.",
+      "params": {
+        "label": "com.dave.workspace",
+        "workingDirectory": "{{daveRoot}}-v2"
+      },
+      "preconditions": [
+        { "assert": "hostService", "value": "com.dave.workspace" }
+      ],
+      "expect": { "produces": ["~/Library/LaunchAgents/com.dave.workspace.plist"] },
+      "rollback": { "trigger": "workspace fails to start", "action": "restore-previous-plist" }
+    },
+    {
+      "id": "step-4",
+      "intent": "verify-boot-health",
+      "description": "Verify pa status exits 0.",
+      "params": { "daveRoot": "{{daveRoot}}-v2" },
+      "expect": { "exitCode": 0 }
+    },
+    {
+      "id": "step-5",
+      "intent": "define-roster-entry",
+      "description": "Register Dex in operator roster.",
+      "params": { "hostId": "dex", "layoutVersion": "v2", "daveRoot": "{{daveRoot}}-v2" }
+    }
+  ]
+}

package/dist/engineering-pa-runbook/reference/hq-dave.runbook.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://stravica.ai/schemas/runbook/1.0",
+  "id": "hq-dave-v1-to-v2",
+  "target": "hq-dave",
+  "description": "Migrate HQ Dave instance from v1 fork to v2 operator-repo.",
+  "version": "1.0.0",
+  "inspectionRef": "inspection-hq-dave.json",
+  "steps": [
+    {
+      "id": "step-1",
+      "intent": "snapshot-v1-fork",
+      "description": "Preserve the v1 fork as rollback point.",
+      "params": { "snapshotSuffix": "pre-v2-{{inspectedAt|date}}" },
+      "preconditions": [
+        { "assert": "workingTreeClean" },
+        { "assert": "onBranch", "value": "main" }
+      ],
+      "expect": { "produces": ["{{daveRoot}}-pre-v2-{{inspectedAt|date}}/"] },
+      "rollback": { "trigger": "v2 instance fails 24h soak", "action": "restore-from-snapshot" }
+    },
+    {
+      "id": "step-2",
+      "intent": "run-migrate-to-v2",
+      "description": "Run migrate-to-v2 CLI against the v1 fork.",
+      "params": {
+        "source": "{{daveRoot}}",
+        "target": "{{daveRoot}}-v2",
+        "dryRun": false
+      },
+      "preconditions": [
+        { "assert": "snapshotExists" },
+        { "assert": "nodeVersion", "value": ">=24" },
+        { "assert": "pnpmOnPath" }
+      ],
+      "expect": { "produces": ["{{daveRoot}}-v2/package.json", "{{daveRoot}}-v2/operator/"] },
+      "rollback": { "trigger": "migrate-to-v2 exits non-zero", "action": "restore-from-snapshot" }
+    },
+    {
+      "id": "step-3",
+      "intent": "update-host-service",
+      "description": "Update the workspace launchd plist to point to the v2 instance.",
+      "params": {
+        "label": "com.dave.workspace",
+        "workingDirectory": "{{daveRoot}}-v2"
+      },
+      "preconditions": [
+        { "assert": "hostService", "value": "com.dave.workspace" }
+      ],
+      "expect": { "produces": ["~/Library/LaunchAgents/com.dave.workspace.plist"] },
+      "rollback": { "trigger": "workspace fails to start", "action": "restore-previous-plist" }
+    },
+    {
+      "id": "step-4",
+      "intent": "verify-boot-health",
+      "description": "Verify pa status exits 0 in the v2 instance.",
+      "params": { "daveRoot": "{{daveRoot}}-v2" },
+      "preconditions": [
+        { "assert": "directoryExists", "value": "{{daveRoot}}-v2" }
+      ],
+      "expect": { "exitCode": 0 }
+    },
+    {
+      "id": "step-5",
+      "intent": "define-roster-entry",
+      "description": "Register hq-dave in the operator roster as a v2 instance.",
+      "params": { "hostId": "hq-dave", "layoutVersion": "v2", "daveRoot": "{{daveRoot}}-v2" }
+    }
+  ]
+}

package/dist/engineering-pa-runbook/reference/smarthome01.runbook.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://stravica.ai/schemas/runbook/1.0",
+  "id": "smarthome01-v1-to-v2",
+  "target": "smarthome01",
+  "description": "Migrate smarthome01 from v1 fork to v2. upstream-triage cron entry is deliberately dropped (operator decision 2026-05-17).",
+  "version": "1.0.0",
+  "inspectionRef": "inspection-smarthome01.json",
+  "steps": [
+    {
+      "id": "step-1",
+      "intent": "snapshot-v1-fork",
+      "description": "Preserve v1 fork.",
+      "params": { "snapshotSuffix": "pre-v2-{{inspectedAt|date}}" },
+      "preconditions": [
+        { "assert": "workingTreeClean" },
+        { "assert": "onBranch", "value": "main" }
+      ],
+      "expect": { "produces": ["{{daveRoot}}-pre-v2-{{inspectedAt|date}}/"] },
+      "rollback": { "trigger": "v2 instance fails 24h soak", "action": "restore-from-snapshot" }
+    },
+    {
+      "id": "step-2",
+      "intent": "drop-cron-entry",
+      "description": "Remove upstream-triage cron entry (operator decision: not carried forward to v2).",
+      "params": { "matchCommand": "upstream-triage" },
+      "preconditions": [
+        { "assert": "cronEntryExists", "value": "upstream-triage" }
+      ],
+      "expect": { "cronEntryAbsent": "upstream-triage" },
+      "rollback": { "trigger": "upstream-triage still required", "action": "restore-cron-entry" },
+      "notes": "Operator confirmed drop on 2026-05-17. upstream-triage is superseded by Dex-side processing."
+    },
+    {
+      "id": "step-3",
+      "intent": "run-migrate-to-v2",
+      "description": "Run migrate-to-v2 CLI.",
+      "params": {
+        "source": "{{daveRoot}}",
+        "target": "{{daveRoot}}-v2",
+        "dryRun": false
+      },
+      "preconditions": [
+        { "assert": "snapshotExists" },
+        { "assert": "nodeVersion", "value": ">=24" },
+        { "assert": "pnpmOnPath" }
+      ],
+      "expect": { "produces": ["{{daveRoot}}-v2/package.json", "{{daveRoot}}-v2/operator/"] },
+      "rollback": { "trigger": "migrate-to-v2 exits non-zero", "action": "restore-from-snapshot" }
+    },
+    {
+      "id": "step-4",
+      "intent": "rewrite-crontab",
+      "description": "Update the 3 remaining cron entries (distill, wsd-ingest, sync) to use the v2 instance path.",
+      "params": {
+        "entries": [
+          { "matchCommand": "distill", "newWorkingDirectory": "{{daveRoot}}-v2" },
+          { "matchCommand": "wsd-ingest", "newWorkingDirectory": "{{daveRoot}}-v2" },
+          { "matchCommand": "sync", "newWorkingDirectory": "{{daveRoot}}-v2" }
+        ]
+      },
+      "preconditions": [
+        { "assert": "cronEntryExists", "value": "distill" },
+        { "assert": "cronEntryExists", "value": "wsd-ingest" },
+        { "assert": "cronEntryExists", "value": "sync" }
+      ],
+      "expect": { "cronEntriesUpdated": 3 }
+    },
+    {
+      "id": "step-5",
+      "intent": "verify-sync-continuity",
+      "description": "Verify sync reaches the dropbox share from the v2 instance.",
+      "params": { "daveRoot": "{{daveRoot}}-v2" },
+      "preconditions": [
+        { "assert": "mountExists", "value": "/mnt/share/dropbox" }
+      ],
+      "expect": { "syncExitCode": 0 }
+    },
+    {
+      "id": "step-6",
+      "intent": "verify-boot-health",
+      "description": "Verify pa status exits 0.",
+      "params": { "daveRoot": "{{daveRoot}}-v2" },
+      "expect": { "exitCode": 0 }
+    },
+    {
+      "id": "step-7",
+      "intent": "define-roster-entry",
+      "description": "Register smarthome01 in operator roster.",
+      "params": { "hostId": "smarthome01", "layoutVersion": "v2", "daveRoot": "{{daveRoot}}-v2" }
+    }
+  ]
+}

package/dist/engineering-pa-runbook/schema/inspection.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stravica.ai/schemas/inspection/1.0",
+  "title": "MigrateInspectionResult",
+  "type": "object",
+  "required": ["host", "runtimes", "scheduled", "mounts", "daveEnv", "paths", "extensions", "inspectedAt"],
+  "properties": {
+    "host": {
+      "type": "object",
+      "required": ["hostname", "os", "osVersion", "arch"],
+      "properties": {
+        "hostname": { "type": "string" },
+        "os": { "type": "string" },
+        "osVersion": { "type": "string" },
+        "arch": { "type": "string" },
+        "chip": { "type": "string" },
+        "memory": { "type": "number" }
+      }
+    },
+    "runtimes": {
+      "type": "object",
+      "required": ["nodeVersion", "pnpmVersion", "gitVersion"],
+      "properties": {
+        "nodeVersion": { "type": ["string", "null"] },
+        "pnpmVersion": { "type": ["string", "null"] },
+        "gitVersion": { "type": ["string", "null"] }
+      }
+    },
+    "scheduled": {
+      "type": "object",
+      "required": ["crontab", "launchdPlists"],
+      "properties": {
+        "crontab": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["schedule", "command"],
+            "properties": {
+              "schedule": { "type": "string" },
+              "command": { "type": "string" }
+            }
+          }
+        },
+        "launchdPlists": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "label": { "type": ["string", "null"] },
+              "program": { "type": ["string", "null"] },
+              "args": {
+                "oneOf": [
+                  { "type": "array", "items": { "type": "string" } },
+                  { "type": "null" }
+                ]
+              },
+              "workingDirectory": { "type": ["string", "null"] },
+              "runAtLoad": { "type": "boolean" },
+              "keepAlive": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+    "mounts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "target", "fsType"],
+        "properties": {
+          "source": { "type": "string" },
+          "target": { "type": "string" },
+          "fsType": { "type": "string" }
+        }
+      }
+    },
+    "daveEnv": {
+      "type": "object",
+      "required": ["daveRoot", "daveRelevantEnvVars", "pathSegments"],
+      "properties": {
+        "daveRoot": { "type": ["string", "null"] },
+        "daveRelevantEnvVars": { "type": "object" },
+        "pathSegments": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "paths": {
+      "type": "object",
+      "required": ["daveRoot", "coreToolsPath", "operatorPath", "layoutVersion"],
+      "properties": {
+        "daveRoot": { "type": ["string", "null"] },
+        "coreToolsPath": { "type": ["string", "null"] },
+        "operatorPath": { "type": ["string", "null"] },
+        "layoutVersion": {
+          "type": "string",
+          "enum": ["v1", "v2", "unknown"]
+        }
+      }
+    },
+    "extensions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "path", "hasManifestEntry"],
+        "properties": {
+          "name": { "type": "string" },
+          "path": { "type": "string" },
+          "hasManifestEntry": { "type": "boolean" }
+        }
+      }
+    },
+    "inspectedAt": { "type": "string" }
+  }
+}

package/dist/engineering-pa-runbook/schema/runbook.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stravica.ai/schemas/runbook/1.0",
+  "title": "MigrationRunbook",
+  "type": "object",
+  "required": ["$schema", "id", "target", "version", "steps"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "id": { "type": "string" },
+    "target": { "type": "string" },
+    "description": { "type": "string" },
+    "version": { "type": "string" },
+    "inspectionRef": { "type": "string" },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/Step" }
+    }
+  },
+  "$defs": {
+    "Step": {
+      "type": "object",
+      "required": ["id", "intent"],
+      "properties": {
+        "id": { "type": "string" },
+        "intent": {
+          "type": "string",
+          "enum": [
+            "snapshot-v1-fork",
+            "run-migrate-to-v2",
+            "rewrite-crontab",
+            "drop-cron-entry",
+            "update-host-service",
+            "verify-sync-continuity",
+            "verify-boot-health",
+            "define-roster-entry"
+          ]
+        },
+        "description": { "type": "string" },
+        "params": { "type": "object" },
+        "preconditions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Condition" }
+        },
+        "expect": { "type": "object" },
+        "rollback": { "$ref": "#/$defs/Rollback" },
+        "notes": { "type": "string" }
+      }
+    },
+    "Condition": {
+      "type": "object",
+      "required": ["assert"],
+      "properties": {
+        "assert": { "type": "string" },
+        "value": {}
+      }
+    },
+    "Rollback": {
+      "type": "object",
+      "required": ["trigger", "action"],
+      "properties": {
+        "trigger": { "type": "string" },
+        "action": { "type": "string" }
+      }
+    }
+  }
+}

package/dist/engineering-pa-runbook/src/validator.mjs

@@ -0,0 +1,167 @@
+// validator.mjs — minimal structural validator for runbook.schema.json and
+// inspection.schema.json. Handles the subset of JSON Schema 2020-12 that
+// the two schemas actually use. No external deps.
+
+const PRIMITIVE_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'null', 'array', 'object']);
+
+/**
+ * Validate data against a JSON Schema (subset).
+ * @param {object} schema - the schema to validate against
+ * @param {unknown} data - the data to validate
+ * @param {object} [rootSchema] - root schema for $ref resolution (defaults to schema)
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validate(schema, data, rootSchema = schema) {
+  const errors = [];
+  _validate(schema, data, rootSchema, '', errors);
+  return { valid: errors.length === 0, errors };
+}
+
+function _validate(schema, data, rootSchema, path, errors) {
+  if (schema === true) return;
+  if (schema === false) {
+    errors.push(`${path || '(root)'}: schema is false`);
+    return;
+  }
+
+  // $ref resolution
+  if (schema.$ref) {
+    const resolved = _resolveRef(schema.$ref, rootSchema);
+    if (!resolved) {
+      errors.push(`${path || '(root)'}: unresolvable $ref ${schema.$ref}`);
+      return;
+    }
+    _validate(resolved, data, rootSchema, path, errors);
+    return;
+  }
+
+  // type check
+  if (schema.type !== undefined) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some(t => _checkType(t, data))) {
+      errors.push(`${path || '(root)'}: expected type ${types.join('|')}, got ${_typeOf(data)}`);
+      return; // no point continuing if type is wrong
+    }
+  }
+
+  // enum
+  if (schema.enum !== undefined) {
+    if (!schema.enum.some(v => _deepEqual(v, data))) {
+      errors.push(`${path || '(root)'}: value ${JSON.stringify(data)} not in enum [${schema.enum.map(v => JSON.stringify(v)).join(', ')}]`);
+    }
+  }
+
+  // object-specific
+  if (_typeOf(data) === 'object' && data !== null) {
+    // required
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required) {
+        if (!Object.prototype.hasOwnProperty.call(data, key)) {
+          errors.push(`${path || '(root)'}: missing required property "${key}"`);
+        }
+      }
+    }
+
+    // properties
+    if (schema.properties) {
+      for (const [key, subSchema] of Object.entries(schema.properties)) {
+        if (Object.prototype.hasOwnProperty.call(data, key)) {
+          _validate(subSchema, data[key], rootSchema, path ? `${path}.${key}` : key, errors);
+        }
+      }
+    }
+
+    // additionalProperties
+    if (schema.additionalProperties !== undefined && schema.properties) {
+      const knownKeys = new Set(Object.keys(schema.properties));
+      for (const key of Object.keys(data)) {
+        if (!knownKeys.has(key)) {
+          if (schema.additionalProperties === false) {
+            errors.push(`${path || '(root)'}: additional property "${key}" not allowed`);
+          } else if (typeof schema.additionalProperties === 'object') {
+            _validate(schema.additionalProperties, data[key], rootSchema, path ? `${path}.${key}` : key, errors);
+          }
+        }
+      }
+    }
+  }
+
+  // array-specific
+  if (Array.isArray(data)) {
+    // minItems
+    if (typeof schema.minItems === 'number' && data.length < schema.minItems) {
+      errors.push(`${path || '(root)'}: array has ${data.length} items, minItems is ${schema.minItems}`);
+    }
+
+    // items
+    if (schema.items !== undefined) {
+      for (let i = 0; i < data.length; i++) {
+        _validate(schema.items, data[i], rootSchema, `${path}[${i}]`, errors);
+      }
+    }
+  }
+
+  // oneOf
+  if (schema.oneOf !== undefined) {
+    const matchCount = schema.oneOf.filter(subSchema => {
+      const sub = [];
+      _validate(subSchema, data, rootSchema, path, sub);
+      return sub.length === 0;
+    }).length;
+    if (matchCount !== 1) {
+      errors.push(`${path || '(root)'}: expected exactly one of oneOf schemas to match, got ${matchCount}`);
+    }
+  }
+
+  // anyOf
+  if (schema.anyOf !== undefined) {
+    const anyMatch = schema.anyOf.some(subSchema => {
+      const sub = [];
+      _validate(subSchema, data, rootSchema, path, sub);
+      return sub.length === 0;
+    });
+    if (!anyMatch) {
+      errors.push(`${path || '(root)'}: value does not match any of anyOf schemas`);
+    }
+  }
+}
+
+function _resolveRef(ref, rootSchema) {
+  // Only handles #/$defs/<name>
+  const match = ref.match(/^#\/\$defs\/(.+)$/);
+  if (!match) return null;
+  const name = match[1];
+  return rootSchema.$defs && rootSchema.$defs[name] ? rootSchema.$defs[name] : null;
+}
+
+function _checkType(type, data) {
+  switch (type) {
+    case 'string': return typeof data === 'string';
+    case 'number': return typeof data === 'number' && !Number.isNaN(data);
+    case 'integer': return typeof data === 'number' && Number.isInteger(data);
+    case 'boolean': return typeof data === 'boolean';
+    case 'null': return data === null;
+    case 'array': return Array.isArray(data);
+    case 'object': return typeof data === 'object' && data !== null && !Array.isArray(data);
+    default: return false;
+  }
+}
+
+function _typeOf(data) {
+  if (data === null) return 'null';
+  if (Array.isArray(data)) return 'array';
+  return typeof data;
+}
+
+function _deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a === 'object') {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every(k => _deepEqual(a[k], b[k]));
+  }
+  return false;
+}