@subbly/plugin-lint 0.0.5 → 0.0.8

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @subbly/plugin-lint
 
+## 0.0.8
+
+### Patch Changes
+
+- Plugin automations are now workflows, as in the builder. The manifest key is `extensions["co.subbly.builder"].workflows` and the instruction files live in `co.subbly.builder/workflows/<slug>.md`. The rule ids `automation/*` are now `workflow/*`. A manifest that still declares `automations` fails rule `manifest/namespace-unknown-key`, as the builder refresh rejects it.
+
+## 0.0.7
+
+### Patch Changes
+
+- A config field may carry `description` beside `label`: a string of 1-300 characters after trimming, shown under the input in the install dialog. Before, the linter rejected it as an unknown key (rule `manifest/namespace-unknown-key`), though the builder accepts it. A blank or over-long description fails rule `field/description`.
+
+## 0.0.6
+
+### Patch Changes
+
+- 937b7e6: A connector marker may carry `liveTools` beside `auth` and `tools`: the read tools that a live page may call. It is a non-empty array of unique tool names, 1-100 characters each, as `tools` is. When `tools` is there too, each live tool must also be in `tools` (rule `connector/live-tools`). A marker with none of `auth`, `tools` and `liveTools` is rejected, as the builder refresh rejects it.
+
 ## 0.0.5
 
 ### Patch Changes

package/README.md

@@ -58,7 +58,7 @@ export default [
 ]
 ```
 
-The gate is cross-file: whether a `plugin.json` is valid depends on `marketplace.json`, and a missing `automations/<slug>.md` is a defect in a file that does not exist. ESLint visits one existing file at a time, so the engine runs once per invocation and hands each file the findings that belong to it. Every rule reaches the editor, absence checks included.
+The gate is cross-file: whether a `plugin.json` is valid depends on `marketplace.json`, and a missing `workflows/<slug>.md` is a defect in a file that does not exist. ESLint visits one existing file at a time, so the engine runs once per invocation and hands each file the findings that belong to it. Every rule reaches the editor, absence checks included.
 
 ## Library
 
@@ -74,7 +74,7 @@ console.log(report.errors.length)
 
 ## What it checks
 
-`marketplace.json` and every plugin manifest, `mcp.json` servers, skill and agent frontmatter, automation declarations against their files, cron floors, script lockfiles, plugin layout, and sandbox paths written in prose. Run `subbly-plugin-lint --rules` for the full list.
+`marketplace.json` and every plugin manifest, `mcp.json` servers, skill and agent frontmatter, workflow declarations against their files, cron floors, script lockfiles, plugin layout, and sandbox paths written in prose. Run `subbly-plugin-lint --rules` for the full list.
 
 ## Two severities
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@subbly/plugin-lint",
-  "version": "0.0.5",
+  "version": "0.0.8",
   "private": false,
   "type": "module",
-  "description": "The Subbly marketplace release gate, offline. Lints marketplace.json, plugin manifests, mcp.json, skills, agents and automations.",
+  "description": "The Subbly marketplace release gate, offline. Lints marketplace.json, plugin manifests, mcp.json, skills, agents and workflows.",
   "license": "MIT",
   "author": "Subbly LTD <oleg@subbly.co> (https://www.subbly.co)",
   "publishConfig": {
@@ -31,10 +31,10 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "engines": {
-    "node": ">=20"
-  },
   "scripts": {
     "test": "node test/lint.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
   }
-}
+}

package/src/cron.mjs

@@ -1,6 +1,6 @@
 // Cron parsing and the builder 15-minute schedule floor.
 //
-// Mirrors packages/core/src/lib/automations/schedule.ts: 101 firings sampled
+// Mirrors packages/core/src/lib/workflows/schedule.ts: 101 firings sampled
 // from 2026-01-01T00:00:00Z, rejected if any gap falls under the floor.
 
 export const SCHEDULE_FLOOR_MINUTES = 15

package/src/eslint-plugin.mjs

@@ -1,7 +1,7 @@
 // ESLint bridge.
 //
 // The release gate is cross-file: whether plugin.json is valid depends on
-// marketplace.json, and a missing automations/<slug>.md is a defect in a file
+// marketplace.json, and a missing workflows/<slug>.md is a defect in a file
 // that does not exist. ESLint visits one existing file at a time, so rules
 // cannot be written that way directly.
 //

package/src/report.mjs

@@ -41,6 +41,7 @@ export const RULES = {
   'field/key-format': 'field keys must match /^[A-Z][A-Z0-9_]*$/',
   'field/key-duplicate': 'a duplicate field key silently overrides the first',
   'field/label': 'label is required, 1-100 characters',
+  'field/description': 'description is optional, 1-300 characters after trimming',
   'field/type': 'type must be "text" or "select"',
   'field/options': 'options belong to select fields and select fields require them',
   'field/public-secret': 'public and secret are mutually exclusive',
@@ -49,24 +50,25 @@ export const RULES = {
   'field/default-required': 'a default plugin cannot declare required fields',
   'field/reserved-key': 'a field key must not restate the PLUGIN_ prefix the builder adds',
 
-  // automations
-  'automation/key-slug': 'automation keys must be valid slugs',
-  'automation/unknown-key': 'a declaration holds exactly name, schedule and model',
-  'automation/name': 'name is required, 1-100 characters',
-  'automation/schedule-syntax': 'schedule must be a cron expression the builder can parse',
-  'automation/schedule-floor': 'schedule must fire at most every 15 minutes',
-  'automation/schedule-unverified': 'this cron syntax cannot be checked offline',
-  'automation/model': 'model must be normal or intelligent-high',
-  'automation/missing-file': 'every declared automation needs its markdown file',
-  'automation/orphan-file': 'every automation file needs a declaration',
-  'automation/empty-file': 'an automation file must not be empty',
-  'automation/frontmatter': 'automation frontmatter is not stripped and leaks into the instruction',
+  // workflows
+  'workflow/key-slug': 'workflow keys must be valid slugs',
+  'workflow/unknown-key': 'a declaration holds exactly name, schedule and model',
+  'workflow/name': 'name is required, 1-100 characters',
+  'workflow/schedule-syntax': 'schedule must be a cron expression the builder can parse',
+  'workflow/schedule-floor': 'schedule must fire at most every 15 minutes',
+  'workflow/schedule-unverified': 'this cron syntax cannot be checked offline',
+  'workflow/model': 'model must be normal or intelligent-high',
+  'workflow/missing-file': 'every declared workflow needs its markdown file',
+  'workflow/orphan-file': 'every workflow file needs a declaration',
+  'workflow/empty-file': 'a workflow file must not be empty',
+  'workflow/frontmatter': 'workflow frontmatter is not stripped and leaks into the instruction',
   'setup/missing-install-skill': 'setup: true requires a skills/install skill',
 
   // connectors and mcp.json
-  'connector/marker': 'a connector marker holds auth, tools or both, and nothing else',
+  'connector/marker': 'a connector marker holds one or more of auth, tools and liveTools, and nothing else',
   'connector/auth': 'auth, when present, is exactly "oauth"',
-  'connector/tools': 'tools is a non-empty array of unique tool names, 1-100 characters each',
+  'connector/tools': 'tools and liveTools are each a non-empty array of unique tool names, 1-100 characters each',
+  'connector/live-tools': 'each live tool is also in tools, when tools is present',
   'connector/name-length': 'connector names are 1-100 characters',
   'connector/undefined-server': 'a declared connector needs a matching mcp.json server',
   'connector/no-mcp': 'declaring a connector requires an mcp.json',

package/src/rules.mjs

@@ -3,7 +3,7 @@
 // Mirrors subbly-builder branch feat/plugins-mcp:
 //   packages/plugins/src/marketplace/{marketplace-manifest,plugin-manifest,mcp-config}.ts
 //   packages/core/src/types/plugin-manifest.ts
-//   packages/core/src/lib/automations/schedule.ts
+//   packages/core/src/lib/workflows/schedule.ts
 //
 // error = the refresh throws, so NO plugin in the marketplace releases.
 // warn  = the builder accepts it, but it is wrong, dead, or broken at runtime.
@@ -34,10 +34,10 @@ const CONNECTOR_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,49}$/
 const CONTENT_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/i
 
 const MANIFEST_KEYS = ['$schema', 'name', 'version', 'description', 'author', 'homepage', 'repository', 'license', 'keywords', 'extensions']
-const NAMESPACE_KEYS = ['displayName', 'image', 'default', 'fields', 'automations', 'setup', 'connectors']
-const FIELD_KEYS = ['key', 'label', 'type', 'required', 'secret', 'public', 'pattern', 'options']
-const AUTOMATION_KEYS = ['name', 'schedule', 'model']
-const AUTOMATION_MODELS = ['normal', 'intelligent-high']
+const NAMESPACE_KEYS = ['displayName', 'image', 'default', 'fields', 'workflows', 'setup', 'connectors']
+const FIELD_KEYS = ['key', 'label', 'description', 'type', 'required', 'secret', 'public', 'pattern', 'options']
+const WORKFLOW_KEYS = ['name', 'schedule', 'model']
+const WORKFLOW_MODELS = ['normal', 'intelligent-high']
 const SERVER_KEYS = ['type', 'url', 'headers']
 
 export const AGENT_TOOLS = ['read_file', 'write_file', 'edit_file', 'apply_patch', 'execute_command', 'get_stock_image', 'web_fetch', 'web_search', 'generate_image', 'restart_preview', 'apply_to_preview', 'tool_run', 'tool_search', 'tool_describe', 'skill']
@@ -53,7 +53,7 @@ export const DEFAULT_ENV_KEYS = [
 
 const RESERVED_SLUG = 'custom'
 
-const MISPLACED = ['agents', 'automations', 'scripts', 'instructions.md']
+const MISPLACED = ['agents', 'workflows', 'scripts', 'instructions.md']
 
 // The builder-maintained symlink to the installed version, the only stable
 // segment prose may use in a sandbox path.
@@ -409,7 +409,7 @@ function lintPluginManifest(root, entry, report) {
   check.boolean('manifest/boolean', `${ns}.setup`, ext.setup)
 
   const fields = lintFields(report, file, at, check, ns, ext, entry.slug)
-  const automations = lintAutomationDeclarations(report, file, at, check, ns, ext)
+  const workflows = lintWorkflowDeclarations(report, file, at, check, ns, ext)
   const connectors = lintConnectors(report, file, at, check, ns, ext)
 
   if (ext.default === true && fields.some((f) => f.required === true)) {
@@ -421,7 +421,7 @@ function lintPluginManifest(root, entry, report) {
     )
   }
 
-  return { fieldKeys: fields.map((f) => f.key).filter(Boolean), automations, connectors, setup: ext.setup === true }
+  return { fieldKeys: fields.map((f) => f.key).filter(Boolean), workflows, connectors, setup: ext.setup === true }
 }
 
 function lintFields(report, file, at, check, ns, ext, slug) {
@@ -458,6 +458,9 @@ function lintFields(report, file, at, check, ns, ext, slug) {
     }
 
     check.string('field/label', `${p}.label`, field.label, { min: 1, max: 100, required: true, label: `${label}.label` })
+    if (field.description !== undefined) {
+      check.string('field/description', `${p}.description`, field.description, { min: 1, max: 300, trim: true, label: `${label}.description` })
+    }
 
     if (field.type !== 'text' && field.type !== 'select') {
       report.error('field/type', file, `${label}.type: expected "text" or "select", received ${JSON.stringify(field.type)}`, at(`${p}.type`))
@@ -507,39 +510,39 @@ function lintFields(report, file, at, check, ns, ext, slug) {
   return ext.fields.filter(isObject)
 }
 
-function lintAutomationDeclarations(report, file, at, check, ns, ext) {
-  if (ext.automations === undefined) return []
-  if (!isObject(ext.automations)) {
-    report.error('automation/key-slug', file, `${ns}.automations: expected object keyed by slug, received ${typeOf(ext.automations)}`, at(`${ns}.automations`))
+function lintWorkflowDeclarations(report, file, at, check, ns, ext) {
+  if (ext.workflows === undefined) return []
+  if (!isObject(ext.workflows)) {
+    report.error('workflow/key-slug', file, `${ns}.workflows: expected object keyed by slug, received ${typeOf(ext.workflows)}`, at(`${ns}.workflows`))
     return []
   }
 
   const slugs = []
-  for (const [slug, decl] of Object.entries(ext.automations)) {
-    const p = `${ns}.automations.${slug}`
-    const label = `automations["${slug}"]`
+  for (const [slug, decl] of Object.entries(ext.workflows)) {
+    const p = `${ns}.workflows.${slug}`
+    const label = `workflows["${slug}"]`
 
     if (slug.length < 1 || slug.length > 64 || !SLUG_PATTERN.test(slug)) {
-      report.error('automation/key-slug', file, `${label}: key ${SLUG_MESSAGE}`, at(p, { key: true }))
+      report.error('workflow/key-slug', file, `${label}: key ${SLUG_MESSAGE}`, at(p, { key: true }))
       continue
     }
     if (!isObject(decl)) {
-      report.error('automation/unknown-key', file, `${label}: expected object, received ${typeOf(decl)}`, at(p))
+      report.error('workflow/unknown-key', file, `${label}: expected object, received ${typeOf(decl)}`, at(p))
       continue
     }
 
-    check.strictKeys('automation/unknown-key', p, decl, AUTOMATION_KEYS, label)
-    check.string('automation/name', `${p}.name`, decl.name, { min: 1, max: 100, trim: true, required: true, label: `${label}.name` })
+    check.strictKeys('workflow/unknown-key', p, decl, WORKFLOW_KEYS, label)
+    check.string('workflow/name', `${p}.name`, decl.name, { min: 1, max: 100, trim: true, required: true, label: `${label}.name` })
 
-    if (check.string('automation/schedule-syntax', `${p}.schedule`, decl.schedule, { min: 1, max: 100, required: true, label: `${label}.schedule` })) {
+    if (check.string('workflow/schedule-syntax', `${p}.schedule`, decl.schedule, { min: 1, max: 100, required: true, label: `${label}.schedule` })) {
       lintSchedule(report, file, at(`${p}.schedule`), label, decl.schedule)
     }
 
-    if (!AUTOMATION_MODELS.includes(decl.model)) {
+    if (!WORKFLOW_MODELS.includes(decl.model)) {
       report.error(
-        'automation/model',
+        'workflow/model',
         file,
-        `${label}.model: expected ${AUTOMATION_MODELS.join(' | ')}, received ${JSON.stringify(decl.model)}`,
+        `${label}.model: expected ${WORKFLOW_MODELS.join(' | ')}, received ${JSON.stringify(decl.model)}`,
         at(`${p}.model`)
       )
     }
@@ -554,17 +557,17 @@ function lintSchedule(report, file, pos, label, schedule) {
     cron = parseCron(schedule)
   } catch (e) {
     if (e instanceof CronUnsupported) {
-      report.warn('automation/schedule-unverified', file, `${label}.schedule contains "${e.message}", which cannot be checked offline`, {
+      report.warn('workflow/schedule-unverified', file, `${label}.schedule contains "${e.message}", which cannot be checked offline`, {
         ...pos,
         hint: 'the builder may accept it; confirm the 15-minute floor by hand',
       })
       return
     }
-    report.error('automation/schedule-syntax', file, `${label}.schedule: invalid cron expression (${e.message})`, pos)
+    report.error('workflow/schedule-syntax', file, `${label}.schedule: invalid cron expression (${e.message})`, pos)
     return
   }
   if (!meetsFloor(cron)) {
-    report.error('automation/schedule-floor', file, `${label}.schedule must fire at most every ${SCHEDULE_FLOOR_MINUTES} minutes`, pos)
+    report.error('workflow/schedule-floor', file, `${label}.schedule must fire at most every ${SCHEDULE_FLOOR_MINUTES} minutes`, pos)
   }
 }
 
@@ -587,9 +590,9 @@ function lintConnectors(report, file, at, check, ns, ext) {
       report.error('connector/marker', file, `${label}: expected object, received ${typeOf(marker)}`, at(p))
       continue
     }
-    check.strictKeys('connector/marker', p, marker, ['auth', 'tools'], label)
-    if (marker.auth === undefined && marker.tools === undefined) {
-      report.error('connector/marker', file, `${label}: declare auth, tools or both`, at(p))
+    check.strictKeys('connector/marker', p, marker, ['auth', 'tools', 'liveTools'], label)
+    if (marker.auth === undefined && marker.tools === undefined && marker.liveTools === undefined) {
+      report.error('connector/marker', file, `${label}: declare auth, tools or liveTools`, at(p))
     }
     if (marker.auth !== undefined && marker.auth !== 'oauth') {
       report.error('connector/auth', file, `${label}.auth: expected "oauth", received ${JSON.stringify(marker.auth)}`, at(`${p}.auth`))
@@ -597,6 +600,10 @@ function lintConnectors(report, file, at, check, ns, ext) {
     if (marker.tools !== undefined) {
       lintToolAllowlist(report, file, at, check, `${p}.tools`, `${label}.tools`, marker.tools)
     }
+    if (marker.liveTools !== undefined) {
+      lintToolAllowlist(report, file, at, check, `${p}.liveTools`, `${label}.liveTools`, marker.liveTools)
+      lintLiveToolsInTools(report, file, at, p, label, marker)
+    }
     names.push(name)
   }
   return names
@@ -624,6 +631,15 @@ function lintToolAllowlist(report, file, at, check, p, label, tools) {
   }
 }
 
+function lintLiveToolsInTools(report, file, at, p, label, marker) {
+  if (!Array.isArray(marker.tools) || !Array.isArray(marker.liveTools)) return
+  for (const [index, tool] of marker.liveTools.entries()) {
+    if (typeof tool === 'string' && !marker.tools.includes(tool)) {
+      report.error('connector/live-tools', file, `${label}.liveTools[${index}]: live tool "${tool}" must also be in tools`, at(`${p}.liveTools.${index}`))
+    }
+  }
+}
+
 // --- mcp.json --------------------------------------------------------------
 
 function lintMcp(root, entry, manifest, report) {
@@ -960,10 +976,10 @@ function lintAgents(root, entry, report) {
   }
 }
 
-// --- automations -----------------------------------------------------------
+// --- workflows -----------------------------------------------------------
 
-function lintAutomationFiles(root, entry, declared, report) {
-  const dir = join(entry.dir, NAMESPACE, 'automations')
+function lintWorkflowFiles(root, entry, declared, report) {
+  const dir = join(entry.dir, NAMESPACE, 'workflows')
   const present = new Set()
 
   for (const dirent of listDir(dir)) {
@@ -975,10 +991,10 @@ function lintAutomationFiles(root, entry, declared, report) {
   const orphans = [...present].filter((s) => !declared.includes(s))
   for (const orphan of orphans) {
     report.error(
-      'automation/orphan-file',
+      'workflow/orphan-file',
       relative(root, join(dir, `${orphan}.md`)),
-      `Invalid automations of ${entry.slug}: files without a manifest declaration: ${orphans.join(', ')}`,
-      { line: 1, hint: `declare it in plugin.json under extensions["${NAMESPACE}"].automations, or delete it` }
+      `Invalid workflows of ${entry.slug}: files without a manifest declaration: ${orphans.join(', ')}`,
+      { line: 1, hint: `declare it in plugin.json under extensions["${NAMESPACE}"].workflows, or delete it` }
     )
   }
 
@@ -986,19 +1002,19 @@ function lintAutomationFiles(root, entry, declared, report) {
     const path = join(dir, `${slug}.md`)
     if (!present.has(slug)) {
       report.error(
-        'automation/missing-file',
+        'workflow/missing-file',
         relative(root, join(entry.dir, 'plugin.json')),
-        `Invalid automations of ${entry.slug}: missing automations/${slug}.md`,
-        { hint: `create ${NAMESPACE}/automations/${slug}.md` }
+        `Invalid workflows of ${entry.slug}: missing workflows/${slug}.md`,
+        { hint: `create ${NAMESPACE}/workflows/${slug}.md` }
       )
       continue
     }
     const text = readIfExists(path) ?? ''
     if (text.trim() === '') {
-      report.error('automation/empty-file', relative(root, path), `Invalid automations of ${entry.slug}: automations/${slug}.md is empty`, { line: 1 })
+      report.error('workflow/empty-file', relative(root, path), `Invalid workflows of ${entry.slug}: workflows/${slug}.md is empty`, { line: 1 })
     }
     if (text.trimStart().startsWith('---')) {
-      report.warn('automation/frontmatter', relative(root, path), 'frontmatter here is not parsed or stripped, so it lands verbatim in the agent instruction', {
+      report.warn('workflow/frontmatter', relative(root, path), 'frontmatter here is not parsed or stripped, so it lands verbatim in the agent instruction', {
         line: 1,
         hint: 'name, schedule and model belong in plugin.json',
       })
@@ -1163,7 +1179,7 @@ export function lint(root, { git = true } = {}) {
     lintMcp(root, entry, manifest, report)
     lintSkills(root, entry, report)
     lintAgents(root, entry, report)
-    lintAutomationFiles(root, entry, manifest?.automations ?? [], report)
+    lintWorkflowFiles(root, entry, manifest?.workflows ?? [], report)
     lintSetup(root, entry, manifest, report)
     lintLayout(root, entry, report)
   }