@captain_z/zsk 1.8.4 → 1.8.5

package/schemas/providers.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@captain_z/zsk/schemas/providers.schema.json",
+  "title": "ZSK Provider Policy",
+  "description": "Project provider capability mappings. Credentials and host startup details belong in host MCP config, not this file.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "providers"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "enum": [1]
+    },
+    "providers": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/providerMapping"
+      }
+    },
+    "adapters": {
+      "description": "Reserved for future project adapter contract overrides. First implementation rejects non-empty adapter overrides.",
+      "type": "object",
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "providerMapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "adapter": {
+          "type": "string",
+          "enum": ["figma", "jira", "confluence", "gitlab"]
+        },
+        "extends": {
+          "type": "string",
+          "minLength": 1
+        },
+        "tools": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "metadata-read": {
+              "$ref": "#/$defs/stringList"
+            },
+            "metadataRead": {
+              "$ref": "#/$defs/stringList"
+            },
+            "node-read": {
+              "$ref": "#/$defs/stringList"
+            },
+            "nodeRead": {
+              "$ref": "#/$defs/stringList"
+            },
+            "asset-export": {
+              "$ref": "#/$defs/stringList"
+            },
+            "assetExport": {
+              "$ref": "#/$defs/stringList"
+            }
+          }
+        }
+      }
+    },
+    "stringList": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    }
+  }
+}

package/schemas/zsk-config.schema.json

@@ -122,7 +122,7 @@
           "$ref": "#/$defs/pathRef"
         },
         "resources": {
-          "description": "Deprecated compatibility alias for paths.raws.",
+          "description": "Compatibility alias for paths.raws.",
           "$ref": "#/$defs/pathRef"
         },
         "raws": {
@@ -158,6 +158,27 @@
         }
       }
     },
+    "providers": {
+      "description": "Project-level provider connection profiles. Credentials should reference env vars or profiles, not inline secrets.",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/providerConfig"
+      }
+    },
+    "resources": {
+      "description": "Resource intents to prepare. Sync materializes only configured resources that produce snapshots.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/resourceConfig"
+      }
+    },
+    "routes": {
+      "description": "Rules that route prepared resources into controlled module or shared consumption artifacts.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/routeConfig"
+      }
+    },
     "tools": {
       "description": "Preferred AI/tool capabilities for project-level workflows.",
       "type": "object",
@@ -195,6 +216,13 @@
         "root": {
           "$ref": "#/$defs/pathRef"
         },
+        "registry": {
+          "description": "Optional module registry used by resource routes and reports.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/moduleRegistryEntry"
+          }
+        },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
@@ -233,6 +261,64 @@
             "scenarioDir": {
               "$ref": "#/$defs/pathRef"
             },
+            "auth": {
+              "description": "Demo login bootstrap. Store only local env-file references and env key names here, never credential values.",
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "required": {
+                  "type": "boolean"
+                },
+                "loginUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "storageState": {
+                  "$ref": "#/$defs/pathRef"
+                },
+                "envFiles": {
+                  "description": "Local files that may define exported env vars, for example ~/.zshrc. Values are read at runtime and are not copied into ZSK artifacts.",
+                  "$ref": "#/$defs/stringList"
+                },
+                "env": {
+                  "description": "Purpose-to-env-key map, for example username: DEMO_USER and password: DEMO_PASSWORD.",
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "selectors": {
+                  "description": "Optional Playwright locators used by the first-login helper to fill configured env values.",
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "properties": {
+                    "username": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "password": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "otp": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "submit": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                },
+                "metadata": {
+                  "$ref": "#/$defs/metadata"
+                }
+              }
+            },
             "playwright": {
               "type": "object",
               "additionalProperties": false,
@@ -346,6 +432,213 @@
         }
       }
     },
+    "providerConfig": {
+      "description": "Provider connection profile. This is intentionally generic so projects can bind Jira, GitHub, GitLab, Confluence, Figma, MCP, command, or future providers without schema churn.",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "type": {
+          "type": "string",
+          "minLength": 1
+        },
+        "adapter": {
+          "type": "string",
+          "minLength": 1
+        },
+        "baseUrl": {
+          "type": "string",
+          "minLength": 1
+        },
+        "auth": {
+          "$ref": "#/$defs/authRef"
+        },
+        "defaults": {
+          "$ref": "#/$defs/metadata"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "resourceConfig": {
+      "description": "Resource intent. `type + id` determines the default raw snapshot path unless output.rawPath overrides it.",
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "type"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "type": {
+          "type": "string",
+          "minLength": 1
+        },
+        "area": {
+          "type": "string",
+          "minLength": 1
+        },
+        "provider": {
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "object",
+              "additionalProperties": true
+            }
+          ]
+        },
+        "source": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "query": {
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "object",
+              "additionalProperties": true
+            }
+          ]
+        },
+        "params": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "classify": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "output": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "rawPath": {
+              "$ref": "#/$defs/pathRef"
+            },
+            "commitRaw": {
+              "type": "boolean"
+            }
+          }
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "routeConfig": {
+      "description": "Route from a prepared resource to a controlled artifact target.",
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["from", "to"],
+      "properties": {
+        "from": {
+          "type": "string",
+          "minLength": 1
+        },
+        "to": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "module": {
+              "type": "string",
+              "minLength": 1
+            },
+            "artifact": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "moduleRegistryEntry": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "authRef": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "env": {
+          "description": "Primary token env var name, or fallback token env var names in priority order.",
+          "$ref": "#/$defs/stringOrStringList"
+        },
+        "tokenEnv": {
+          "description": "Bearer or provider-token env var name.",
+          "$ref": "#/$defs/stringOrStringList"
+        },
+        "accessTokenEnv": {
+          "description": "Access-token env var name.",
+          "$ref": "#/$defs/stringOrStringList"
+        },
+        "apiTokenEnv": {
+          "description": "API-token env var name.",
+          "$ref": "#/$defs/stringOrStringList"
+        },
+        "usernameEnv": {
+          "description": "Basic-auth username env var name.",
+          "$ref": "#/$defs/stringOrStringList"
+        },
+        "passwordEnv": {
+          "description": "Basic-auth password env var name.",
+          "$ref": "#/$defs/stringOrStringList"
+        },
+        "cookieEnv": {
+          "description": "Raw Cookie header env var name.",
+          "$ref": "#/$defs/stringOrStringList"
+        },
+        "sessionCookieEnv": {
+          "description": "Session-cookie env var name.",
+          "$ref": "#/$defs/stringOrStringList"
+        },
+        "cookies": {
+          "description": "Cookie-name to env-var-name map.",
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "tokenHeader": {
+          "type": "string",
+          "minLength": 1
+        },
+        "tokenScheme": {
+          "type": "string",
+          "minLength": 1
+        },
+        "profile": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
     "sourceType": {
       "description": "Raw source role. Common examples include srs, prd, design, api_contract, backend_repo, test_case, design_asset, vendor_doc, and manual, but projects may define their own roles.",
       "type": "string",
@@ -360,6 +653,34 @@
         "type": {
           "$ref": "#/$defs/sourceType"
         },
+        "adapter": {
+          "description": "Concrete built-in source adapter id. Runtime tools such as playwright_cli or computer_use are accepted only as compatibility fallback aliases; prefer fallback for those.",
+          "type": "string",
+          "enum": ["figma", "jira", "confluence", "gitlab", "playwright-cli", "playwright_cli", "playwright", "playwright-mcp", "playwright_mcp", "computer-use", "computer_use", "browser-use", "browser_use", "manual", "export"]
+        },
+        "fallback": {
+          "description": "Optional runtime fallback tools used after built-in source adapters and generic fetches. Playwright fallbacks may enable browser-backed capture; computer_use is observation-only and is not invoked by prepare sync.",
+          "$ref": "#/$defs/sourceFallbackRef"
+        },
+        "fallbackTools": {
+          "description": "Compatibility alias for fallback.",
+          "$ref": "#/$defs/sourceFallbackToolList"
+        },
+        "provider": {
+          "description": "Deprecated compatibility field. Prefer adapter for built-in source adapters or mcpProvider for MCP provider bindings.",
+          "type": "string",
+          "minLength": 1
+        },
+        "mcpProvider": {
+          "description": "Explicit MCP provider binding name. The provider must be mapped by built-in provider registry or .zsk/providers.yaml.",
+          "type": "string",
+          "minLength": 1
+        },
+        "mcpServer": {
+          "description": "Deprecated compatibility alias for mcpProvider.",
+          "type": "string",
+          "minLength": 1
+        },
         "origin": {
           "$ref": "#/$defs/originRef"
         },
@@ -367,11 +688,60 @@
           "description": "Optional explicit materialized snapshot path. Omit this for entry-point sources such as a Figma file, Confluence space, repository, or issue query.",
           "$ref": "#/$defs/pathRef"
         },
+        "snapshotRequirements": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "assets": {
+              "type": "string",
+              "enum": ["required", "recommended", "optional"]
+            },
+            "metadata": {
+              "$ref": "#/$defs/metadata"
+            }
+          }
+        },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
       }
     },
+    "sourceFallbackRef": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/sourceFallbackToolList"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "acquisition": {
+              "$ref": "#/$defs/sourceFallbackToolList"
+            },
+            "observation": {
+              "$ref": "#/$defs/sourceFallbackToolList"
+            },
+            "tools": {
+              "$ref": "#/$defs/sourceFallbackToolList"
+            },
+            "metadata": {
+              "$ref": "#/$defs/metadata"
+            }
+          }
+        }
+      ]
+    },
+    "sourceFallbackToolList": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/sourceFallbackTool"
+      },
+      "uniqueItems": true
+    },
+    "sourceFallbackTool": {
+      "type": "string",
+      "enum": ["playwright-cli", "playwright_cli", "playwright", "playwright-mcp", "playwright_mcp", "computer-use", "computer_use", "browser-use", "browser_use", "manual", "export"]
+    },
     "sourceTree": {
       "description": "A raw source reference or a grouping object whose keys mirror .zsk/raws/prepare responsibility lanes.",
       "oneOf": [
@@ -409,6 +779,18 @@
           "type": "string",
           "minLength": 1
         },
+        "adapter": {
+          "type": "string",
+          "minLength": 1
+        },
+        "mcpProvider": {
+          "type": "string",
+          "minLength": 1
+        },
+        "mcpServer": {
+          "type": "string",
+          "minLength": 1
+        },
         "path": {
           "$ref": "#/$defs/pathRef"
         },
@@ -539,6 +921,10 @@
           "type": "string",
           "minLength": 1
         },
+        "extends": {
+          "type": "string",
+          "minLength": 1
+        },
         "stages": {
           "type": "array",
           "items": {
@@ -563,6 +949,12 @@
           },
           "uniqueItems": true
         },
+        "resources": {
+          "$ref": "#/$defs/stringList"
+        },
+        "artifacts": {
+          "$ref": "#/$defs/stringList"
+        },
         "required": {
           "type": "boolean"
         },
@@ -589,6 +981,19 @@
         "writeScope": {
           "$ref": "#/$defs/stringList"
         },
+        "writeScopes": {
+          "$ref": "#/$defs/stringList"
+        },
+        "staffing": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "maxParallel": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
         "outputs": {
           "$ref": "#/$defs/stringList"
         },
@@ -615,6 +1020,17 @@
       },
       "uniqueItems": true
     },
+    "stringOrStringList": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "$ref": "#/$defs/stringList"
+        }
+      ]
+    },
     "scriptSync": {
       "description": "Resource produced by a deterministic script command.",
       "type": "object",

package/templates/project-init/.zsk/README.md

@@ -0,0 +1,48 @@
+# ZSK Workspace
+
+This workspace is config-driven.
+
+Do not create empty resource directories. `zsk init` creates the governance
+entrypoints only. Resource snapshot directories under `.zsk/raws/**` are created
+by `zsk prepare sync` only after `.zsk/config.yaml` declares a resource and the
+sync run produces a snapshot.
+
+## Working Model
+
+| Path | Kind | Created By | Commit Policy |
+| --- | --- | --- | --- |
+| `.zsk/config.yaml` | config | init/user | commit |
+| `.zsk/roles.yaml` | staffing policy | init/user | commit |
+| `.zsk/docs/**` | governance docs | init/user | commit |
+| `.zsk/templates/**` | reusable templates | init | commit |
+| `.zsk/raws/README.md` | resource snapshot contract | init | commit |
+| `.zsk/raws/**/snapshot.md` | generated summary | prepare sync | commit |
+| `.zsk/raws/**/metadata.yaml` | generated provenance | prepare sync | commit |
+| `.zsk/raws/**/source.json` | raw provider payload | prepare sync | ignore by default |
+| `.zsk/raws/**/assets/**` | raw provider assets | prepare sync | ignore by default |
+| `.zsk/modules/index.md` | module registry view | init/module add | commit |
+| `.zsk/modules/<module>/**` | module work surface | module add/user | commit |
+| `.zsk/modules/<module>/_issues/**` | module task cards | prepare sync/user | commit |
+| `.zsk/issues/**` | global/cross-module issues | init/prepare/user | commit |
+| `.zsk/evidence/prepare/sync-report.md` | prepare report | prepare sync | commit |
+| `.zsk/runs/**` | runtime state | commands | ignore |
+| `.zsk/state/**` | runtime state | commands | ignore |
+| `.zsk/tmp/**` | temporary files | commands | ignore |
+
+## Rules
+
+- Raw snapshots live under `.zsk/raws/**`.
+- Module work lives under `.zsk/modules/**`.
+- Module-local issues live under `.zsk/modules/<module>/_issues/**`.
+- Global or cross-module blockers live under `.zsk/issues/**`.
+- Provider connections, resource intents, and routes are declared in
+  `.zsk/config.yaml`.
+- Staffing policy lives in `.zsk/roles.yaml`; a specific run's chosen agents
+  belong in evidence, not in the template.
+
+## Next Steps
+
+1. Edit `.zsk/config.yaml`.
+2. Add modules with `zsk module init -m <module-id> --name "<Module Name>"`.
+3. Run `zsk config check`.
+4. Run `zsk prepare sync` when resource acquisition is intentionally allowed.