@sous-io/sous 0.2.36 → 1.0.1

package/sous.config.schema.json

@@ -1,33 +1,11 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sous-io.github.io/sous/sous.config.schema.json",
+  "title": "Sous config",
   "type": "object",
   "properties": {
-    "$schema": {
-      "type": "string"
-    },
-    "version": {
-      "type": "number",
-      "const": 1
-    },
-    "_env": {
-      "type": "object",
-      "propertyNames": {
-        "type": "string"
-      },
-      "additionalProperties": {
-        "type": "string"
-      }
-    },
-    "_vars": {
-      "type": "object",
-      "propertyNames": {
-        "type": "string"
-      },
-      "additionalProperties": {
-        "type": "string"
-      }
-    },
     "_aliases": {
+      "description": "Include aliases: a name to one base directory or several, tried in order.",
       "type": "object",
       "propertyNames": {
         "type": "string"
@@ -46,10 +24,46 @@
         ]
       }
     },
-    "name": {
+    "_env": {
+      "description": "Config variables read from the environment: each name mapped to an environment variable."
+    },
+    "_vars": {
+      "description": "Config variables, used as ${name}. Values may refer to each other in any order."
+    },
+    "$schema": {
+      "description": "The JSON Schema the file declares, for editors. Sous ignores it.",
       "type": "string"
     },
+    "budgets": {
+      "description": "Time budgets in milliseconds, by \"<category>\" or \"<category>:<name>\"; false turns a warning off.",
+      "type": "object",
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "const": false
+          }
+        ]
+      },
+      "default": {}
+    },
+    "cli": {
+      "description": "CLI settings: cli.pick.\"<command words>\": \"<plugin>\" picks between two commands claiming the same words.",
+      "type": "object",
+      "properties": {
+        "pick": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {}
+        }
+      }
+    },
     "compilation": {
+      "description": "What to compile: targets, their outputs, source comments, the state file, overwriting files sous did not write.",
       "type": "object",
       "properties": {
         "_vars": {
@@ -62,13 +76,27 @@
           }
         },
         "includeSourceComments": {
+          "default": false,
           "type": "boolean"
         },
+        "overwriteUntracked": {
+          "default": true,
+          "type": "boolean"
+        },
+        "stateFile": {
+          "default": "${sousDir}/sous.state.json",
+          "type": "string"
+        },
         "targets": {
+          "default": [],
           "type": "array",
           "items": {
             "type": "object",
             "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
               "_vars": {
                 "type": "object",
                 "propertyNames": {
@@ -84,12 +112,39 @@
               "entryGlob": {
                 "type": "string"
               },
+              "content": {
+                "type": "string"
+              },
               "globBase": {
                 "type": "string"
               },
+              "includeSourceComments": {
+                "type": "boolean"
+              },
               "generateRuntimeContext": {
                 "type": "boolean"
               },
+              "transforms": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "origin": {
+                "type": "object",
+                "properties": {
+                  "plugin": {
+                    "type": "string"
+                  },
+                  "recipe": {
+                    "type": "string"
+                  },
+                  "repository": {
+                    "type": "string"
+                  }
+                },
+                "additionalProperties": false
+              },
               "outputs": {
                 "type": "array",
                 "items": {
@@ -127,6 +182,12 @@
                     },
                     "destinationDir": {
                       "type": "string"
+                    },
+                    "transforms": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
                     }
                   },
                   "additionalProperties": false
@@ -140,95 +201,130 @@
           }
         }
       },
-      "required": [
-        "targets"
-      ],
       "additionalProperties": false
     },
-    "runtimeContext": {
+    "intents": {
+      "description": "Which plugin's intent wins when two add one name: intents.replace.\"<intent>\": \"<plugin>\".",
       "type": "object",
       "properties": {
-        "gitRoot": {
-          "type": "string"
+        "replace": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {}
+        }
+      }
+    },
+    "limits": {
+      "description": "The loop-detection limits.",
+      "type": "object",
+      "properties": {
+        "configPasses": {
+          "type": "integer"
         },
-        "outputPath": {
-          "type": "string"
+        "rebuildsChanging": {
+          "type": "integer"
         },
-        "taskFileRoot": {
-          "type": "string"
+        "rebuildsRepeating": {
+          "type": "integer"
         },
-        "branchPattern": {
-          "type": "string"
+        "runDepth": {
+          "type": "integer"
+        },
+        "sameIntentDepth": {
+          "type": "integer"
+        },
+        "eventDepth": {
+          "type": "integer"
         }
       },
-      "required": [
-        "gitRoot",
-        "outputPath",
-        "taskFileRoot"
-      ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "default": {}
     },
-    "tools": {
+    "mcp": {
+      "description": "MCP server settings: mcp.include and mcp.exclude pick tools by name, with globs.",
       "type": "object",
-      "propertyNames": {
-        "type": "string"
-      },
-      "additionalProperties": {
-        "type": "object",
-        "properties": {
-          "command": {
+      "properties": {
+        "include": {
+          "type": "array",
+          "items": {
             "type": "string"
           },
-          "args": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
+          "description": "Only tools whose names match these globs."
+        },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string"
           },
-          "promptFile": {
+          "default": [],
+          "description": "Leaves out tools whose names match these globs."
+        }
+      },
+      "additionalProperties": false
+    },
+    "name": {
+      "description": "A display name for the project.",
+      "type": "string"
+    },
+    "plugins": {
+      "description": "Which plugins load, which never load, and each plugin's own options (S1).",
+      "type": "object",
+      "properties": {
+        "discover": {
+          "enum": [
+            "dependencies",
+            "scan"
+          ],
+          "default": "dependencies"
+        },
+        "load": {
+          "type": "array",
+          "items": {
             "type": "string"
-          }
+          },
+          "default": []
         },
-        "required": [
-          "command"
-        ],
-        "additionalProperties": false
+        "disabled": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        },
+        "options": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object"
+          },
+          "default": {}
+        }
       }
     },
     "repos": {
+      "description": "The repositories this project trusts, by short name.",
       "type": "object",
-      "propertyNames": {
-        "type": "string",
-        "pattern": "^[a-z][a-z0-9-]*$"
-      },
+      "default": {},
       "additionalProperties": {
         "type": "object",
+        "description": "One trusted repository. Adding it trusts it.",
         "properties": {
           "url": {
-            "anyOf": [
-              {
-                "type": "string",
-                "format": "uri"
-              },
-              {
-                "type": "string",
-                "minLength": 1
-              }
-            ]
+            "type": "string",
+            "description": "Where the repository lives."
           },
           "enabled": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "False opts out of a repository sous provides itself."
           },
           "provider": {
             "type": "string",
-            "enum": [
-              "github",
-              "gitlab",
-              "local"
-            ]
+            "description": "The repository host, when the URL does not give it away."
           },
           "alwaysPull": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Install a newer in-range version whenever one exists."
           },
           "addedAt": {
             "type": "string"
@@ -237,26 +333,88 @@
             "type": "string"
           }
         },
-        "required": [
-          "url"
-        ],
-        "additionalProperties": false
+        "additionalProperties": true
       }
     },
-    "subscriptions": {
+    "runtimeContext": {
+      "description": "The runtime context file a target with generateRuntimeContext includes: git branch and task file.",
       "type": "object",
-      "propertyNames": {
-        "type": "string",
-        "pattern": "^[a-z][a-z0-9-]*(\\/[a-z][a-z0-9-]*)?$"
+      "properties": {
+        "gitRoot": {
+          "type": "string",
+          "description": "The git repository branch detection reads (${var} allowed)."
+        },
+        "outputPath": {
+          "type": "string",
+          "description": "Where the runtime context file is written."
+        },
+        "taskFileRoot": {
+          "type": "string",
+          "description": "The directory task files live in."
+        },
+        "branchPattern": {
+          "type": "string",
+          "description": "A regular expression; only matching branches look for a task file."
+        }
+      },
+      "required": [
+        "gitRoot",
+        "outputPath",
+        "taskFileRoot"
+      ],
+      "additionalProperties": false
+    },
+    "services": {
+      "description": "Which plugin's replacement of a service wins: services.replace.\"<name>\": \"<plugin>\".",
+      "type": "object",
+      "properties": {
+        "replace": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {}
+        }
+      }
+    },
+    "store": {
+      "description": "The machine-wide recipe store.",
+      "type": "object",
+      "default": {},
+      "properties": {
+        "maxBytes": {
+          "type": "integer",
+          "default": 1073741824,
+          "description": "Size cap past which old entries are collected."
+        },
+        "freshnessSeconds": {
+          "type": "integer",
+          "default": 300,
+          "description": "How long a fetched index stays fresh."
+        },
+        "watchPollSeconds": {
+          "type": "integer",
+          "default": 300,
+          "description": "How often watch mode checks upstream."
+        }
       },
+      "additionalProperties": false
+    },
+    "subscriptions": {
+      "description": "What this project subscribes to, keyed by namespace or namespace/recipe.",
+      "type": "object",
+      "default": {},
       "additionalProperties": {
         "type": "object",
+        "description": "One subscription, to a namespace or to one recipe.",
         "properties": {
           "enabled": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "False switches it off on this machine, keeping its pins."
           },
           "range": {
-            "type": "string"
+            "type": "string",
+            "description": "The version range. Default `*`."
           },
           "prerelease": {
             "type": "boolean"
@@ -271,26 +429,83 @@
             "type": "string"
           }
         },
-        "additionalProperties": false
+        "additionalProperties": true
       }
     },
-    "store": {
+    "tools": {
+      "description": "Tools you can launch with `sous launch <name>`: command, args, promptFile, headless.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "command": {
+            "type": "string",
+            "description": "The command to run."
+          },
+          "args": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Arguments always passed, before yours."
+          },
+          "promptFile": {
+            "type": "string",
+            "description": "A file whose content is passed as the last argument."
+          },
+          "headless": {
+            "type": "object",
+            "properties": {
+              "command": {
+                "type": "string"
+              },
+              "args": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "additionalProperties": false,
+            "description": "The command and arguments for a headless run; the prompt is sent on standard input."
+          }
+        },
+        "additionalProperties": false
+      },
+      "default": {}
+    },
+    "varMappings": {
+      "description": "Environment variable names bound to recipe variables (conf.d/520-var-mappings.jsonc).",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "default": {}
+    },
+    "version": {
+      "description": "The config format version. This sous understands version 1.",
+      "const": 1
+    },
+    "watch": {
+      "description": "Watch mode: more paths that trigger a full rebuild, the debounce, and how often to check upstream.",
       "type": "object",
       "properties": {
-        "maxBytes": {
+        "pollSeconds": {
           "type": "integer",
-          "exclusiveMinimum": 0,
-          "maximum": 9007199254740991
+          "description": "How often watch mode checks upstream for newer recipes, in seconds; 0 never. Default: store.watchPollSeconds."
         },
-        "freshnessSeconds": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 9007199254740991
+        "paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "More files, directories or globs whose change triggers a full rebuild."
         },
-        "watchPollSeconds": {
+        "debounceMs": {
           "type": "integer",
-          "minimum": 0,
-          "maximum": 9007199254740991
+          "default": 200,
+          "description": "How long to wait for more changes before building, in milliseconds."
         }
       },
       "additionalProperties": false
@@ -298,52 +513,56 @@
     "recipes": {
       "type": "object",
       "properties": {
-        "skills": {
+        "memories": {
+          "description": "Which recipe memories memory targets and the #memories view take, and in what order.",
           "type": "object",
+          "additionalProperties": false,
           "properties": {
-            "outputs": {
+            "first": {
               "type": "array",
               "items": {
                 "type": "string"
-              }
+              },
+              "default": [],
+              "description": "Recipe keys, globs or /regular expressions/ whose memories come first, in this order."
+            },
+            "exclude": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "Recipe keys, globs or /regular expressions/ whose memories are left out."
             }
           },
-          "additionalProperties": false
+          "default": {}
         },
-        "memories": {
+        "skills": {
+          "description": "Where skills go (outputs, `${var}` allowed) and directories of your own skills (include).",
           "type": "object",
           "properties": {
-            "first": {
+            "outputs": {
               "type": "array",
               "items": {
                 "type": "string"
-              }
+              },
+              "default": [],
+              "description": "Directories skills are also written to."
             },
-            "exclude": {
+            "include": {
               "type": "array",
               "items": {
                 "type": "string"
-              }
+              },
+              "default": [],
+              "description": "Directories of your own skills, compiled like a recipe's."
             }
           },
-          "additionalProperties": false
+          "additionalProperties": false,
+          "default": {}
         }
-      },
-      "additionalProperties": false
-    },
-    "varMappings": {
-      "type": "object",
-      "propertyNames": {
-        "type": "string",
-        "pattern": "^[A-Z][A-Z0-9_]*$"
-      },
-      "additionalProperties": {
-        "type": "string",
-        "pattern": "^([a-z][a-z0-9-]*:)?[a-z][a-z0-9-]*\\/[a-z][a-z0-9-]*\\/[a-z][a-zA-Z0-9]*$"
       }
     }
   },
-  "additionalProperties": false,
-  "$id": "https://sous-io.github.io/sous/sous.config.schema.json",
-  "title": "Sous config"
+  "additionalProperties": false
 }

package/bin/run.js

@@ -1,51 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { handOffToProjectInstall, isEnvFlagOn } from "../src/lib/project-install.mjs";
-
-// A project that installs @sous-io/sous itself has pinned the version its
-// templates and lockfile were written against, so that copy does the work.
-// This runs before anything else is loaded: when a project copy is found, its
-// own bin is imported into this process and this one loads nothing further
-// (see src/lib/project-install.mjs for the rules, and SOUS_NO_DELEGATE to
-// keep the invoked copy running).
-const ownRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const handedOff = await handOffToProjectInstall({ ownRoot });
-
-if (!handedOff) {
-  // The CLI runs from TypeScript source; register tsx before oclif dynamically
-  // imports any command module. Resolving "tsx" from this file (rather than a
-  // $PKG_ROOT/node_modules path) works in every install layout: repo clone,
-  // global install (nested deps), and local/npx installs (hoisted deps).
-  const { register } = await import("tsx/esm/api");
-  register();
-
-  // `sous --version` is answered here rather than by oclif, whose answer is
-  // its user agent string. Plain, it is the version alone; `--verbose` adds
-  // the package, where it is installed, the platform and the Node build.
-  const argv = process.argv.slice(2);
-  const { isVersionRequest, printVersion } = await import("../src/lib/version-report.ts");
-  if (isVersionRequest(argv)) {
-    printVersion(argv, ownRoot);
-  } else {
-    await runCommand();
-  }
-}
-
-async function runCommand() {
-  const { execute, settings } = await import("@oclif/core");
-
-  // tsx (above) already makes .ts imports work, so oclif's own auto-transpile
-  // machinery is redundant; leaving it on makes every downstream run warn that
-  // the (unshipped) typescript devDependency is missing.
-  settings.enableAutoTranspile = false;
-
-  // oclif's development mode turns on its debug setting, which makes every error
-  // it prints a raw stack trace. Sous reports its own errors as sentences (see
-  // src/utils/command-errors.ts), so development mode is switched on only when
-  // SOUS_DEBUG asks for the traces; anything that gets past a command's own
-  // reporting then prints its stack too.
-  const debugRequested = isEnvFlagOn(process.env.SOUS_DEBUG);
-
-  await execute({ development: debugRequested, dir: import.meta.url });
-}