ai-spector 0.9.21 → 0.9.25

package/contracts/schemas/lifecycle.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kari-writer/contracts/schemas/lifecycle.schema.json",
+  "title": "DocopsLifecycle",
+  "type": "object",
+  "required": ["version", "intent", "adapter", "updatedAt", "updatedBy", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 1 },
+    "intent": { "enum": ["greenfield", "migrate"] },
+    "adapter": { "enum": ["ai-spector", "custom", "none"] },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "updatedBy": { "type": "string", "minLength": 1 },
+    "steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "enum": [
+              "project-created",
+              "git-connected",
+              "docops-init",
+              "local-adapter-ready",
+              "legacy-aligned",
+              "registry-synced",
+              "data-source-added",
+              "first-docs-generated",
+              "review-queue-synced",
+              "first-push-synced"
+            ]
+          },
+          "status": { "enum": ["pending", "in_progress", "done", "skipped", "blocked"] },
+          "completedAt": { "type": "string", "format": "date-time" },
+          "helpRef": { "type": "string" },
+          "blockedReason": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/contracts/schemas/prototype/config.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kari-writer.local/contracts/schemas/prototype/config.schema.json",
+  "title": "PrototypeConfig",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schemaVersion", "buildMode"],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "version": {
+      "type": "integer",
+      "description": "Legacy alias used by ai-spector CLI"
+    },
+    "buildMode": {
+      "type": "string",
+      "enum": ["static", "spa"]
+    },
+    "techStack": {
+      "type": "string",
+      "enum": ["html", "vue", "react", "nuxt", "next", "svelte", "angular"]
+    },
+    "prototypeDir": {
+      "type": "string",
+      "description": "Repo-relative prototype source folder (default: prototype)"
+    },
+    "srcDir": {
+      "type": "string",
+      "description": "Repo-relative source folder (default: prototype/src)"
+    },
+    "htpasswdFile": {
+      "type": "string",
+      "description": "Repo-relative nginx htpasswd path (default: prototype/.htpasswd)"
+    },
+    "basicAuth": {
+      "type": "object",
+      "properties": {
+        "username": { "type": "string", "minLength": 1 },
+        "password": { "type": "string" },
+        "setAt": { "type": "string" }
+      }
+    },
+    "listScreenDoc": { "type": "string" },
+    "screenIndexSection": { "type": "string" },
+    "screenDetailDir": { "type": "string" },
+    "defaultTheme": { "type": "string" },
+    "defaultScreenId": { "type": "string" },
+    "prototypeBypassAuth": { "type": "boolean" },
+    "reviewHost": { "type": "string" },
+    "projectId": { "type": "string" },
+    "deployVersion": { "type": "string" },
+    "directReviewUrl": { "type": "boolean" }
+  }
+}

package/contracts/schemas/prototype/screen-map.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kari-writer.local/contracts/schemas/prototype/screen-map.schema.json",
+  "title": "PrototypeScreenMap",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schemaVersion", "buildMode", "screens"],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "buildMode": {
+      "type": "string",
+      "enum": ["static", "spa"]
+    },
+    "defaultScreenId": { "type": "string" },
+    "defaultScreen": { "$ref": "#/$defs/screenEntry" },
+    "reviewHost": { "type": "string" },
+    "projectId": { "type": "string" },
+    "deployVersion": { "type": "string" },
+    "directReviewUrl": { "type": "boolean" },
+    "screens": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/screenEntry" }
+    }
+  },
+  "$defs": {
+    "screenEntry": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["screenId", "displayName", "screenDocPath", "prototypePath", "route_exists"],
+      "properties": {
+        "screenId": { "type": "string", "minLength": 1 },
+        "displayName": { "type": "string" },
+        "screenDocPath": {
+          "type": "string",
+          "description": "Language-neutral screen design doc path (no docs/ prefix)"
+        },
+        "screenDocs": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Per-language repo-relative doc paths"
+        },
+        "prototypePath": { "type": "string" },
+        "route_exists": { "type": "boolean" },
+        "reviewUrl": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/contracts/schemas/registry/document.entity.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kari-writer.local/contracts/schemas/registry/document.entity.schema.json",
+  "title": "DocopsDocumentEntity",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schemaVersion",
+    "entityId",
+    "kind",
+    "docType",
+    "logicalPath",
+    "repoDocs"
+  ],
+  "properties": {
+    "schemaVersion": { "type": "integer", "const": 1 },
+    "entityId": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "kind": { "type": "string", "enum": ["document", "data_source"] },
+    "docType": { "type": "string", "minLength": 1 },
+    "logicalPath": { "type": "string", "minLength": 1 },
+    "repoDocs": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "displayName": { "type": "string" },
+    "aliases": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "createdAt": { "type": "string" },
+    "updatedAt": { "type": "string" }
+  }
+}

package/contracts/schemas/registry/manifest.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kari-writer.local/contracts/schemas/registry/manifest.schema.json",
+  "title": "DocopsRegistryManifest",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schemaVersion", "buildMode"],
+  "properties": {
+    "schemaVersion": { "type": "integer", "const": 1 },
+    "buildMode": { "type": "string", "enum": ["static", "spa"] },
+    "defaultScreenId": { "type": "string" },
+    "reviewHost": { "type": "string" },
+    "projectId": { "type": "string" },
+    "deployVersion": { "type": "string" },
+    "directReviewUrl": { "type": "boolean" },
+    "themeName": { "type": "string" }
+  }
+}

package/contracts/schemas/registry/screen.entity.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kari-writer.local/contracts/schemas/registry/screen.entity.schema.json",
+  "title": "DocopsScreenEntity",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schemaVersion",
+    "screenId",
+    "kind",
+    "prototypePath",
+    "route_exists"
+  ],
+  "properties": {
+    "schemaVersion": { "type": "integer", "const": 1 },
+    "screenId": { "type": "string", "minLength": 1 },
+    "kind": { "type": "string", "const": "prototype_screen" },
+    "displayName": { "type": "string" },
+    "documentEntityId": {
+      "type": ["string", "null"],
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "prototypePath": { "type": "string", "minLength": 1 },
+    "route_exists": { "type": "boolean" },
+    "reviewUrl": { "type": ["string", "null"] },
+    "updatedAt": { "type": "string" }
+  }
+}

package/contracts/schemas/review/registry.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kari-writer.local/contracts/schemas/review/registry.schema.json",
+  "title": "ReviewRegistry",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["version", "documents"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 3
+    },
+    "documents": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/documentEntry" }
+    }
+  },
+  "$defs": {
+    "vote": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["by", "username", "role", "decision", "at"],
+      "properties": {
+        "by": { "type": "string" },
+        "username": { "type": "string" },
+        "role": { "type": "string", "enum": ["user", "client"] },
+        "decision": { "type": "string", "enum": ["approve", "decline"] },
+        "at": { "type": "string" },
+        "note": { "type": "string" }
+      }
+    },
+    "track": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["status", "votes"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "approved", "rejected", "needs_review"]
+        },
+        "votes": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/vote" }
+        },
+        "quorumMetAt": { "type": ["string", "null"] },
+        "closedAt": { "type": ["string", "null"] },
+        "closedBy": { "type": ["string", "null"] },
+        "closeReason": { "type": ["string", "null"] },
+        "reopenedAt": { "type": ["string", "null"] },
+        "invalidatedAt": { "type": ["string", "null"] }
+      }
+    },
+    "documentEntry": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["logicalPath", "overallStatus", "internal", "client"],
+      "properties": {
+        "logicalPath": { "type": "string", "minLength": 1 },
+        "docPath": { "type": "string" },
+        "contentHash": { "type": "string" },
+        "snapshotRef": { "type": "string" },
+        "overallStatus": {
+          "type": "string",
+          "enum": ["pending_internal", "pending_client", "approved", "rejected"]
+        },
+        "internal": { "$ref": "#/$defs/track" },
+        "client": { "$ref": "#/$defs/track" },
+        "lastEventAt": { "type": "string" }
+      }
+    }
+  }
+}

package/contracts/schemas/review/review.config.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kari-writer.local/contracts/schemas/review/review.config.schema.json",
+  "title": "ReviewConfig",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schemaVersion", "extends"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "extends": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Preset id (e.g. kaopiz-default)"
+    },
+    "gate": { "type": "object", "additionalProperties": true },
+    "baseline": { "type": "object", "additionalProperties": true },
+    "rules": { "type": "object", "additionalProperties": true },
+    "overrides": { "type": "object", "additionalProperties": true },
+    "suppressions": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": true }
+    },
+    "required_section_paths": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["source"],
+      "properties": {
+        "source": {
+          "type": "string",
+          "description": "Who last wrote this file (e.g. db, agent, cli)"
+        }
+      }
+    }
+  }
+}

package/dist/cli.js

@@ -10,7 +10,7 @@ import { applyPrimaryLanguageOutputs } from "./core/graph/translation.js";
 import { loadDocflowConfig } from "./core/config/load.js";
 import { validateGraph, formatIssues } from "./core/operations/validate.js";
 import { runInit } from "./core/operations/init.js";
-import { runDocopsInit, runDocopsMigrate, runDocopsCommentsMigrate, runDocopsRegistrySync, runDocopsReviewRegistryMigrate, runDocopsStatus, runDocopsCheck, runDocopsLayout } from "./core/operations/docops.js";
+import { runDocopsInit, runDocopsMigrate, runDocopsCommentsMigrate, runDocopsRegistrySync, runDocopsReviewRegistryMigrate, runDocopsStatus, runDocopsCheck, runDocopsLayout, runDocopsGuide } from "./core/operations/docops.js";
 import { runLifecycleSync } from "./core/operations/lifecycle.js";
 import { runLangAdd, runLangSetClient, runLangSetInternal } from "./core/operations/lang.js";
 import { runLangQueueFailed, runLangQueueFail, runLangQueuePending, runLangQueueResolved, runLangQueueRetry, runLangQueueScan, } from "./core/operations/lang-queue.js";
@@ -1400,6 +1400,19 @@ docops
     });
     process.exitCode = code;
 });
+docops
+    .command("guide")
+    .description("Agent migration guide: current vs expected structure, files, config — start here when user says migrate")
+    .option("--json", "JSON output for agents")
+    .option("--prompt", "Print only the agent prompt")
+    .action(async (opts, cmd) => {
+    const code = await runDocopsGuide({
+        root: projectRootOpt(cmd),
+        json: opts.json,
+        prompt: opts.prompt,
+    });
+    process.exitCode = code;
+});
 docops
     .command("init")
     .description("Scaffold Writer-ready .docops/ contract")
@@ -1423,7 +1436,19 @@ docops
     .option("--repair", "Fill gaps in existing .docops/ without overwriting")
     .option("--templates-only", "Copy templates only")
     .option("--from-docflow", "Split legacy docflow.config.json into docops.config.json + engine.json")
+    .option("--guide", "Show agent migration guide (current vs expected); alias for docops guide")
+    .option("--json", "JSON output (with --guide)")
+    .option("--prompt", "Agent prompt only (with --guide)")
     .action(async (opts, cmd) => {
+    if (opts.guide) {
+        await runDocopsMigrate({
+            root: projectRootOpt(cmd),
+            guide: true,
+            json: opts.json,
+            prompt: opts.prompt,
+        });
+        return;
+    }
     await runDocopsMigrate({
         root: projectRootOpt(cmd),
         dryRun: opts.dryRun,