@opensoftware/contracts 2.5.0 → 2.7.0

package/skill-catalog/skill-catalog.schema.json

@@ -0,0 +1,177 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/skill-catalog/skill-catalog.schema.json",
+  "title": "SkillCatalog",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The last segment of the skill's folder."
+          },
+          "description": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The description of its front matter; null without one."
+          },
+          "source": {
+            "type": "object",
+            "properties": {
+              "folder": {
+                "type": "string",
+                "minLength": 1
+              },
+              "repository": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The URL of the other Git repository, as the entry `git+<url>#<ref>:<path>` names it."
+              },
+              "commit": {
+                "type": "string",
+                "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$",
+                "description": "The commit of the other repository that factory.lock pins; none while factory.lock has no pin."
+              }
+            },
+            "required": [
+              "folder"
+            ],
+            "description": "Where the skill comes from."
+          },
+          "needs": {
+            "type": "object",
+            "properties": {
+              "secrets": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[A-Z0-9_]+$",
+                  "description": "The variable of a secret in a sandbox (ADR 0068), like \"LINEAR_TOKEN\"."
+                }
+              },
+              "hosts": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9-]+(\\.[a-z0-9-]+)*$",
+                  "description": "A host as an entry of `sandbox.egress`, like \"api.linear.app\"."
+                }
+              }
+            },
+            "required": [
+              "secrets",
+              "hosts"
+            ],
+            "description": "What it needs, from the `metadata` of its front matter."
+          },
+          "agents": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "secrets": {
+                  "type": "object",
+                  "properties": {},
+                  "unevaluatedProperties": {
+                    "type": "string",
+                    "pattern": "^ref:[a-z][a-z0-9-]*/[A-Za-z0-9_./-]+$",
+                    "description": "A reference to a secret, resolved at the egress proxy, never in the sandbox: \"ref:<provider>/<name>\"."
+                  },
+                  "description": "The agent's reference whose variable is each secret the skill needs, by the variable."
+                },
+                "lacks": {
+                  "type": "object",
+                  "properties": {
+                    "secrets": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "pattern": "^[A-Z0-9_]+$",
+                        "description": "The variable of a secret in a sandbox (ADR 0068), like \"LINEAR_TOKEN\"."
+                      }
+                    },
+                    "hosts": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "pattern": "^[a-z0-9-]+(\\.[a-z0-9-]+)*$",
+                        "description": "A host as an entry of `sandbox.egress`, like \"api.linear.app\"."
+                      }
+                    }
+                  },
+                  "required": [
+                    "secrets",
+                    "hosts"
+                  ],
+                  "description": "Each needed secret the agent does not declare, and each needed host its sandbox does not allow."
+                }
+              },
+              "required": [
+                "name",
+                "secrets",
+                "lacks"
+              ],
+              "description": "An agent that uses a skill."
+            },
+            "description": "Each agent that uses it, sorted by name."
+          },
+          "files": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The files of its folder, by their path below it, sorted."
+          },
+          "body": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The text of SKILL.md below the line that ends its front matter, all of it without front matter; null without a\nSKILL.md that is UTF-8 text."
+          },
+          "problems": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The problems of its own files as `factory lint` prints them, relative to the folder of factory.yaml, and a folder\nwithout a SKILL.md."
+          }
+        },
+        "required": [
+          "name",
+          "description",
+          "source",
+          "needs",
+          "agents",
+          "files",
+          "body",
+          "problems"
+        ],
+        "description": "One skill, also one that lint refuses: then `problems` names why."
+      }
+    }
+  },
+  "required": [
+    "skills"
+  ],
+  "description": "What `factory skills` of factory-spec prints (ADR 0141, ADR 0143): every skill the factory's agents use, read with\nthe rules of `factory lint` (ADR 0140), sorted by name. The console reads it for its pages `/skills` and\n`/skills/<name>`, so it never parses a SKILL.md itself."
+}

package/typespec/factory-definition.tsp

@@ -110,7 +110,10 @@ model Agent {
   /** MCP servers: `registry:<name>@<version>` or `<name>@<version>`. */
   mcp?: string[];
 
-  /** Paths to skill folders. */
+  /**
+   * The agent's skills: each a path to a skill folder, or a folder of another Git repository at a ref,
+   * `git+<url>#<ref>:<path>`, which `factory plan` pins in factory.lock (ADR 0146).
+   */
   skills?: string[];
 
   secrets?: SecretReference[];

package/typespec/factory-lock.tsp

@@ -21,6 +21,29 @@ model FactoryLock {
    * counts only while its `range` is the range factory.yaml declares.
    */
   adapters?: Record<Record<FactoryLockAdapterPin>>;
+
+  /**
+   * The skills of other Git repositories that `factory plan` pinned, by the skill's name (ADR 0146). A pin counts only
+   * while its `source` is the entry factory.yaml declares; the foreman and `factory render` fetch its commit and check
+   * its hash.
+   */
+  skills?: Record<FactoryLockSkillPin>;
+}
+
+/** One skill of another Git repository at the commit its ref had when `factory plan` pinned it. */
+@extension("additionalProperties", Json<false>)
+model FactoryLockSkillPin {
+  /** The entry of `skills` in factory.yaml that the pin was resolved from, `git+<url>#<ref>:<path>`. */
+  @pattern("^git\\+.+#[^:]+:.+$")
+  source: string;
+
+  /** The full commit, 40 hexadecimal characters, or 64 in a repository of SHA-256. */
+  @pattern("^([0-9a-f]{40}|[0-9a-f]{64})$")
+  commit: string;
+
+  /** The hash of the skill folder's files in the form of Go's modules: "h1:" and the base64 of a SHA-256. */
+  @pattern("^h1:[A-Za-z0-9+/]{43}=$")
+  hash: string;
 }
 
 /** One registry MCP server at its exact version, with the npm package or the remote it starts. */

package/typespec/main.tsp

@@ -17,4 +17,6 @@ import "./foreman-api.tsp";
 import "./sandbox.tsp";
 import "./factory-lock.tsp";
 import "./access.tsp";
+import "./skill-catalog.tsp";
+import "./person-proof.tsp";
 import "./health.tsp";

package/typespec/person-proof.tsp

@@ -0,0 +1,79 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+import "./access.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/** 43 characters of base64url without padding: 32 bytes, like a SHA-256 or an Ed25519 public key. */
+@pattern("^[A-Za-z0-9_-]{43}$")
+scalar Base64url32 extends string;
+
+/**
+ * The claims of a person proof (ADR 0151): the JSON Web Token that the console signs for one call of a module API in
+ * the name of a person, sent in the header `OSF-Person`, signed with `alg` "Ed25519" and `typ` "osf-person+jwt". It is
+ * bound to one module, one request and 30 seconds. Open: a module ignores a claim it does not know.
+ */
+model PersonProof {
+  /** The issuer: "console" for the console, or the name a team gives its own tool in the modules' setting. */
+  iss: Name;
+
+  /** The person, as the module records the actor's `id`: an email in lower case, or the sign-in proxy's value. */
+  @minLength(1)
+  sub: string;
+
+  /** The name to show, recorded as the actor's `displayName`. */
+  @minLength(1)
+  name?: string;
+
+  /** The person's role from the access file at the time of the call. */
+  role: AccessRole;
+
+  /** The module the call goes to: "foreman", "intake" or "gatekeeper". */
+  aud: Name;
+
+  /** When it was signed, in seconds since 1970-01-01T00:00:00Z. */
+  @minValue(0)
+  iat: safeint;
+
+  /** When it ends, in seconds since 1970-01-01T00:00:00Z; at most 60 seconds after `iat`. */
+  @minValue(0)
+  exp: safeint;
+
+  /** The request's method in upper case. */
+  @pattern("^[A-Z]+$")
+  method: string;
+
+  /** The request's path as sent in the request line, without the query. */
+  @pattern("^/[^?#]*$")
+  path: string;
+
+  /** The SHA-256 of the request's body bytes as sent, in base64url without padding. */
+  bodyDigest: Base64url32;
+}
+
+/**
+ * The public keys of an issuer of person proofs (ADR 0151): a JSON Web Key Set (RFC 7517), as the console publishes it
+ * at `/.well-known/jwks.json`. The first key of the issuer's setting signs; every key here verifies.
+ */
+@extension("additionalProperties", Json<false>)
+model PersonKeys {
+  @minItems(1)
+  keys: PersonKey[];
+}
+
+/** One Ed25519 public key. Closed: a key with its private part `d` or any other member is invalid. */
+@extension("additionalProperties", Json<false>)
+model PersonKey {
+  kty: "OKP";
+  crv: "Ed25519";
+  alg: "Ed25519";
+  use: "sig";
+
+  /** The key's JWK thumbprint (RFC 7638) with SHA-256; a proof names it in its `kid`. */
+  kid: Base64url32;
+
+  /** The public key. */
+  x: Base64url32;
+}

package/typespec/skill-catalog.tsp

@@ -0,0 +1,94 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+import "./factory-definition.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/**
+ * What `factory skills` of factory-spec prints (ADR 0141, ADR 0143): every skill the factory's agents use, read with
+ * the rules of `factory lint` (ADR 0140), sorted by name. The console reads it for its pages `/skills` and
+ * `/skills/<name>`, so it never parses a SKILL.md itself.
+ */
+model SkillCatalog {
+  skills: CatalogSkill[];
+}
+
+/** One skill, also one that lint refuses: then `problems` names why. */
+model CatalogSkill {
+  /** The last segment of the skill's folder. */
+  @minLength(1)
+  name: string;
+
+  /** The description of its front matter; null without one. */
+  description: string | null;
+
+  /** Where the skill comes from. */
+  source: CatalogSkillSource;
+
+  /** What it needs, from the `metadata` of its front matter. */
+  needs: SkillNeeds;
+
+  /** Each agent that uses it, sorted by name. */
+  agents: CatalogSkillAgent[];
+
+  /** The files of its folder, by their path below it, sorted. */
+  files: string[];
+
+  /**
+   * The text of SKILL.md below the line that ends its front matter, all of it without front matter; null without a
+   * SKILL.md that is UTF-8 text.
+   */
+  body: string | null;
+
+  /**
+   * The problems of its own files as `factory lint` prints them, relative to the folder of factory.yaml, and a folder
+   * without a SKILL.md.
+   */
+  problems: string[];
+}
+
+/**
+ * A folder of the factory's repository, relative to the folder of factory.yaml, like "skills/release-notes"; or, for a
+ * skill of another Git repository, its folder there with the repository's URL and the commit factory.lock pins
+ * (ADR 0146).
+ */
+model CatalogSkillSource {
+  @minLength(1)
+  folder: string;
+
+  /** The URL of the other Git repository, as the entry `git+<url>#<ref>:<path>` names it. */
+  @minLength(1)
+  repository?: string;
+
+  /** The commit of the other repository that factory.lock pins; none while factory.lock has no pin. */
+  @pattern("^([0-9a-f]{40}|[0-9a-f]{64})$")
+  commit?: string;
+}
+
+/** The secrets a skill needs, by the variable that holds each in a sandbox, and the hosts it reaches (ADR 0140). */
+model SkillNeeds {
+  secrets: SkillSecretName[];
+  hosts: SkillHost[];
+}
+
+/** An agent that uses a skill. */
+model CatalogSkillAgent {
+  @minLength(1)
+  name: string;
+
+  /** The agent's reference whose variable is each secret the skill needs, by the variable. */
+  secrets: Record<SecretReference>;
+
+  /** Each needed secret the agent does not declare, and each needed host its sandbox does not allow. */
+  lacks: SkillNeeds;
+}
+
+/** The variable of a secret in a sandbox (ADR 0068), like "LINEAR_TOKEN". */
+@pattern("^[A-Z0-9_]+$")
+scalar SkillSecretName extends string;
+
+/** A host as an entry of `sandbox.egress`, like "api.linear.app". */
+@pattern("^[a-z0-9-]+(\\.[a-z0-9-]+)*$")
+scalar SkillHost extends string;