@subbly/plugin-lint 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @subbly/plugin-lint
+
+## 0.0.1
+
+### Patch Changes
+
+- First release. The Subbly marketplace release gate, offline. The builder reads every plugin in one refresh and the refresh is all-or-nothing, so one error in one plugin blocks the release of all of them. This package runs the same 94 checks on your machine before you commit, over `marketplace.json`, 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. Three entry points share one engine: the `subbly-plugin-lint` command, which has no runtime dependencies so a bare CI job works, with `--strict`, `--format unix|json|github`, `--root`, `--no-git` and `--rules`; an ESLint plugin at `@subbly/plugin-lint/eslint` that shows the same findings inline as you type, absence checks included; and the package itself as a library exporting `lint()`, `RULES` and `FORMATTERS`.

package/README.md

@@ -0,0 +1,91 @@
+# @subbly/plugin-lint
+
+The Subbly marketplace release gate, offline.
+
+The builder reads every plugin in one refresh, and the refresh is all-or-nothing: one error in one plugin blocks the release of all of them. This package runs the same checks on your machine before you commit.
+
+## Install
+
+```bash
+pnpm add -D @subbly/plugin-lint
+```
+
+## Command line
+
+Run it from the marketplace root, the directory holding `marketplace.json`.
+
+```bash
+subbly-plugin-lint                 # human output
+subbly-plugin-lint --strict        # warnings fail too
+subbly-plugin-lint --format unix   # file:line:col, for editors
+subbly-plugin-lint --format json
+subbly-plugin-lint --format github # GitHub Actions annotations
+subbly-plugin-lint --root ../shop  # lint another checkout
+subbly-plugin-lint --no-git        # skip the version-bump check
+subbly-plugin-lint --rules         # list every rule
+```
+
+Exit code is 0 when there are no errors, 1 otherwise. It has no runtime dependencies, so it works in a bare CI job.
+
+`--root` also turns the git checks off, since comparing against `origin/main` only makes sense in the checkout you are standing in.
+
+## ESLint
+
+The plugin surfaces the same findings inline as you type. Set your editor's ESLint extension to validate `json` and `markdown`.
+
+```js
+// eslint.config.mjs
+import json from '@eslint/json'
+import markdown from '@eslint/markdown'
+import subbly from '@subbly/plugin-lint/eslint'
+
+const gate = { 'subbly/errors': 'error', 'subbly/warnings': 'warn' }
+
+export default [
+  {
+    files: ['marketplace.json', 'plugins/**/*.json'],
+    language: 'json/json',
+    plugins: { json, subbly },
+    rules: gate,
+  },
+  {
+    files: ['plugins/**/*.md'],
+    language: 'markdown/gfm',
+    languageOptions: { frontmatter: 'yaml' },
+    plugins: { markdown, subbly },
+    rules: gate,
+  },
+]
+```
+
+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.
+
+## Library
+
+```js
+import { lint, FORMATTERS, RULES } from '@subbly/plugin-lint'
+
+const report = lint(process.cwd(), { git: false })
+console.log(FORMATTERS.stylish(report))
+console.log(report.errors.length)
+```
+
+`lint(root, { git })` returns a report with `findings`, `errors` and `warnings`. Each finding carries `level`, `ruleId`, `file`, `message`, `line`, `col` and an optional `hint`. `RULES` maps every rule id to a one-line description.
+
+## 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.
+
+## Two severities
+
+**error** means the refresh throws, so no plugin in the marketplace releases.
+
+**warn** means the builder accepts it, but it is wrong, dead, or broken at runtime.
+
+## Tests
+
+```bash
+pnpm test
+```
+
+Each case builds a throwaway marketplace in a temp directory, lints it, and asserts on the rule id that fired. Asserting on ids rather than message text means wording can change without breaking the suite.

package/bin/subbly-plugin-lint.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Lints a Subbly marketplace against the builder's release gate.
+//
+//   subbly-plugin-lint                    human output
+//   subbly-plugin-lint --format unix      file:line:col, for editors and CI
+//   subbly-plugin-lint --format json
+//   subbly-plugin-lint --format github    GitHub Actions annotations
+//   subbly-plugin-lint --strict           warnings also fail
+//   subbly-plugin-lint --root <dir>       lint somewhere other than the cwd
+//   subbly-plugin-lint --no-git           skip the version-bump check
+//   subbly-plugin-lint --rules            list every rule and exit
+//
+// Exit 0 when there are no errors, 1 otherwise.
+
+import { lint } from '../src/rules.mjs'
+import { FORMATTERS, RULES } from '../src/report.mjs'
+
+const argv = process.argv.slice(2)
+
+function flag(name, fallback) {
+  const i = argv.indexOf(`--${name}`)
+  if (i === -1) return fallback
+  const next = argv[i + 1]
+  return next && !next.startsWith('--') ? next : true
+}
+
+if (argv.includes('--rules')) {
+  const width = Math.max(...Object.keys(RULES).map((r) => r.length))
+  for (const [id, description] of Object.entries(RULES)) {
+    console.log(`${id.padEnd(width)}  ${description}`)
+  }
+  console.log(`\n${Object.keys(RULES).length} rules.`)
+  process.exit(0)
+}
+
+const explicitRoot = flag('root', null)
+const root = explicitRoot === null || explicitRoot === true ? process.cwd() : explicitRoot
+const format = flag('format', 'stylish')
+const strict = argv.includes('--strict')
+
+if (!FORMATTERS[format]) {
+  console.error(`Unknown format ${JSON.stringify(format)}. Available: ${Object.keys(FORMATTERS).join(', ')}`)
+  process.exit(2)
+}
+
+// Comparing against origin/main only makes sense for the checkout you are in,
+// so an explicit --root (a fixture, a temp copy) turns the git checks off.
+const git = !argv.includes('--no-git') && explicitRoot === null
+
+const report = lint(root, { git })
+const output = FORMATTERS[format](report)
+if (output.trim()) console.log(output)
+
+process.exit(report.errors.length > 0 || (strict && report.warnings.length > 0) ? 1 : 0)

package/index.mjs

@@ -0,0 +1,11 @@
+// The linter as a library.
+//
+//   import { lint, FORMATTERS } from '@subbly/plugin-lint'
+//   const report = lint(process.cwd(), { git: false })
+//   console.log(FORMATTERS.stylish(report))
+//
+// The ESLint plugin lives behind its own entry: '@subbly/plugin-lint/eslint'.
+
+export { lint, envVarName, PLUGIN_SCHEMA_URL, MCP_SCHEMA_URL, NAMESPACE, AGENT_TOOLS, DEFAULT_ENV_KEYS, CURRENT_LINK } from './src/rules.mjs'
+export { RULES, FORMATTERS, Report } from './src/report.mjs'
+export { SCHEDULE_FLOOR_MINUTES, parseCron, meetsFloor, CronUnsupported } from './src/cron.mjs'

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@subbly/plugin-lint",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "description": "The Subbly marketplace release gate, offline. Lints marketplace.json, plugin manifests, mcp.json, skills, agents and automations.",
+  "license": "MIT",
+  "author": "Subbly LTD <oleg@subbly.co> (https://www.subbly.co)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/subbly/subbly-plugin-examples.git",
+    "directory": "packages/plugin-lint"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "subbly",
+    "plugin",
+    "marketplace",
+    "lint",
+    "eslint-plugin"
+  ],
+  "bin": {
+    "subbly-plugin-lint": "bin/subbly-plugin-lint.mjs"
+  },
+  "exports": {
+    ".": "./index.mjs",
+    "./eslint": "./src/eslint-plugin.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "index.mjs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node test/lint.test.mjs"
+  }
+}

package/src/cron.mjs

@@ -0,0 +1,131 @@
+// Cron parsing and the builder 15-minute schedule floor.
+//
+// Mirrors packages/core/src/lib/automations/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
+
+const CRON_ALIASES = {
+  '@hourly': '0 * * * *',
+  '@daily': '0 0 * * *',
+  '@weekly': '0 0 * * 0',
+  '@monthly': '0 0 1 * *',
+  '@yearly': '0 0 1 1 *',
+}
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec']
+const DAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat']
+
+export class CronUnsupported extends Error {}
+
+function expandField(spec, min, max, names) {
+  const out = new Set()
+  for (const part of spec.split(',')) {
+    const piece = part.trim()
+    if (piece === '') throw new Error('empty field element')
+    if (/[LW#?]/i.test(piece)) throw new CronUnsupported(piece)
+
+    const [rangePart, stepPart] = piece.split('/')
+    const step = stepPart === undefined ? 1 : Number(stepPart)
+    if (!Number.isInteger(step) || step < 1) throw new Error(`bad step "${stepPart}"`)
+
+    let lo
+    let hi
+    if (rangePart === '*') {
+      lo = min
+      hi = max
+    } else if (rangePart.includes('-')) {
+      const [a, b] = rangePart.split('-')
+      lo = toNumber(a, names)
+      hi = toNumber(b, names)
+    } else {
+      lo = toNumber(rangePart, names)
+      hi = stepPart === undefined ? lo : max
+    }
+    if (lo < min || hi > max || lo > hi) throw new Error(`value out of range in "${piece}"`)
+    for (let v = lo; v <= hi; v += step) out.add(v)
+  }
+  return out
+}
+
+function toNumber(token, names) {
+  const t = token.trim()
+  if (/^\d+$/.test(t)) return Number(t)
+  if (names) {
+    const i = names.indexOf(t.toLowerCase().slice(0, 3))
+    if (i !== -1) return i
+  }
+  throw new Error(`unrecognized value "${t}"`)
+}
+
+/** Returns {fields} or throws. Mirrors what cron-parser accepts, minus L/W/#. */
+export function parseCron(expression) {
+  const expr = (CRON_ALIASES[expression.trim().toLowerCase()] ?? expression).trim()
+  const parts = expr.split(/\s+/)
+  if (parts.length !== 5 && parts.length !== 6) {
+    throw new Error(`expected 5 or 6 fields, got ${parts.length}`)
+  }
+  const [sec, min, hour, dom, mon, dow] = parts.length === 6 ? parts : ['0', ...parts]
+  const dowSet = expandField(dow, 0, 7, DAYS)
+  if (dowSet.has(7)) dowSet.add(0)
+  return {
+    seconds: expandField(sec, 0, 59),
+    minutes: expandField(min, 0, 59),
+    hours: expandField(hour, 0, 23),
+    dom: expandField(dom, 1, 31),
+    months: expandField(mon, 1, 12, MONTHS),
+    dow: dowSet,
+    domRestricted: dom.trim() !== '*',
+    dowRestricted: dow.trim() !== '*',
+  }
+}
+
+/**
+ * Replicates scheduleMeetsFloor: 101 firings from 2026-01-01T00:00:00Z, reject
+ * if any gap is under 15 minutes. Iterates by day so a yearly cron stays cheap.
+ */
+export function meetsFloor(cron) {
+  if (cron.seconds.size > 1) return false // sub-minute firings
+
+  const minutesOfDay = []
+  for (const h of [...cron.hours].sort((a, b) => a - b)) {
+    for (const m of [...cron.minutes].sort((a, b) => a - b)) minutesOfDay.push(h * 60 + m)
+  }
+  minutesOfDay.sort((a, b) => a - b)
+  if (minutesOfDay.length === 0) return true
+
+  // A same-day gap under the floor fails regardless of which days match.
+  for (let i = 1; i < minutesOfDay.length; i++) {
+    if (minutesOfDay[i] - minutesOfDay[i - 1] < SCHEDULE_FLOOR_MINUTES) return false
+  }
+
+  // Then walk real days for the wrap-around gap between consecutive fire days.
+  const start = Date.UTC(2026, 0, 1)
+  let firings = 0
+  let previousDayIndex = null
+  const DAY_LIMIT = 366 * 120
+
+  for (let day = 0; day < DAY_LIMIT && firings <= 101; day++) {
+    const date = new Date(start + day * 86400000)
+    if (!dayMatches(cron, date)) continue
+
+    if (previousDayIndex !== null) {
+      const dayGap = (day - previousDayIndex) * 1440
+      const wrap = dayGap - minutesOfDay[minutesOfDay.length - 1] + minutesOfDay[0]
+      if (wrap < SCHEDULE_FLOOR_MINUTES) return false
+    }
+    previousDayIndex = day
+    firings += minutesOfDay.length
+  }
+  return true
+}
+
+function dayMatches(cron, date) {
+  if (!cron.months.has(date.getUTCMonth() + 1)) return false
+  const domHit = cron.dom.has(date.getUTCDate())
+  const dowHit = cron.dow.has(date.getUTCDay())
+  // Standard cron: when both are restricted the match is OR, not AND.
+  if (cron.domRestricted && cron.dowRestricted) return domHit || dowHit
+  if (cron.domRestricted) return domHit
+  if (cron.dowRestricted) return dowHit
+  return true
+}

package/src/eslint-plugin.mjs

@@ -0,0 +1,74 @@
+// 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
+// that does not exist. ESLint visits one existing file at a time, so rules
+// cannot be written that way directly.
+//
+// Instead the engine runs once per ESLint invocation and each file is handed
+// the findings that belong to it. Every rule in src/rules.mjs reaches
+// the editor, absence-checks included, and the engine stays the one place a
+// rule is written.
+
+import { relative } from 'node:path'
+import { lint } from './rules.mjs'
+
+let cache = null
+
+function findingsFor(cwd, filename) {
+  // ESLint lints files in one pass, so a single engine run covers all of them.
+  // Keyed on cwd so a watching editor re-runs when the workspace changes.
+  if (!cache || cache.cwd !== cwd) {
+    const byFile = new Map()
+    // git comparisons are for CI, not for a keystroke in the editor.
+    for (const finding of lint(cwd, { git: false }).findings) {
+      if (!byFile.has(finding.file)) byFile.set(finding.file, [])
+      byFile.get(finding.file).push(finding)
+    }
+    cache = { cwd, byFile, at: Date.now() }
+  }
+  return cache.byFile.get(relative(cwd, filename)) ?? []
+}
+
+/** Editors keep one process alive, so stale results need a short lifetime. */
+const MAX_CACHE_MS = 1000
+
+function level(want) {
+  return {
+    meta: {
+      type: want === 'error' ? 'problem' : 'suggestion',
+      docs: {
+        description:
+          want === 'error'
+            ? 'Release-gate errors: the marketplace refresh throws, so no plugin releases'
+            : 'Release-gate warnings: accepted by the builder, but wrong, dead, or broken at runtime',
+      },
+      schema: [],
+    },
+    create(context) {
+      if (cache && Date.now() - cache.at > MAX_CACHE_MS) cache = null
+
+      const report = () => {
+        for (const finding of findingsFor(context.cwd, context.filename)) {
+          if (finding.level !== want) continue
+          context.report({
+            loc: { line: finding.line, column: finding.col },
+            message: `${finding.message} [${finding.ruleId}]`,
+          })
+        }
+      }
+
+      // Document is the momoa (JSON) root; root is the mdast (markdown) one.
+      // Program covers a plain JS file, should this ever lint one.
+      return { 'Document:exit': report, 'root:exit': report, 'Program:exit': report }
+    },
+  }
+}
+
+export default {
+  meta: { name: 'subbly', version: '1.0.0' },
+  rules: {
+    errors: level('error'),
+    warnings: level('warn'),
+  },
+}

package/src/frontmatter.mjs

@@ -0,0 +1,101 @@
+// Line-aware frontmatter reader.
+//
+// The builder parses with front-matter + js-yaml safeLoad. We support the flat
+// key/scalar/list shapes plugin content actually uses and refuse anything
+// richer, rather than guessing and quietly disagreeing with js-yaml.
+//
+// Every key records the line it sits on so findings can point at it.
+
+export function readFrontmatter(text) {
+  const stripped = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
+  const lines = stripped.split(/\r?\n/)
+  const opener = lines[0]?.trimEnd()
+
+  if (opener !== '---' && opener !== '= yaml =') {
+    // front-matter yields {} here, so the builder fails on the missing
+    // description rather than on a parse error.
+    return { fenced: false, attributes: {}, keyLines: {}, body: stripped, bodyLine: 1 }
+  }
+
+  let close = -1
+  for (let i = 1; i < lines.length; i++) {
+    const trimmed = lines[i].trimEnd()
+    if (trimmed === '---' || trimmed === '...' || trimmed === '= yaml =') {
+      close = i
+      break
+    }
+  }
+  if (close === -1) {
+    return { fenced: false, unterminated: true, attributes: {}, keyLines: {}, body: stripped, bodyLine: 1 }
+  }
+
+  const attributes = {}
+  const keyLines = {}
+  let pendingKey = null
+
+  for (let i = 1; i < close; i++) {
+    const raw = lines[i]
+    const lineNumber = i + 1
+    if (!raw.trim() || raw.trim().startsWith('#')) continue
+
+    const item = raw.match(/^\s+-\s*(.*)$/)
+    if (item && pendingKey) {
+      if (!Array.isArray(attributes[pendingKey])) attributes[pendingKey] = []
+      attributes[pendingKey].push(unquote(item[1]))
+      continue
+    }
+
+    const pair = raw.match(/^([A-Za-z0-9_$-]+)\s*:\s*(.*)$/)
+    if (!pair) {
+      return { fenced: true, unsupported: raw.trim(), unsupportedLine: lineNumber, attributes: {}, keyLines: {}, body: '', bodyLine: close + 2 }
+    }
+
+    const [, key, rawValue] = pair
+    if (key in keyLines) {
+      return { fenced: true, duplicate: key, duplicateLine: lineNumber, attributes: {}, keyLines: {}, body: '', bodyLine: close + 2 }
+    }
+    keyLines[key] = lineNumber
+
+    const value = rawValue.trim()
+    if (value === '') {
+      attributes[key] = null
+      pendingKey = key
+    } else if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim()
+      attributes[key] = inner ? inner.split(',').map((s) => unquote(s.trim())) : []
+      pendingKey = null
+    } else {
+      attributes[key] = unquote(value)
+      pendingKey = null
+    }
+  }
+
+  return {
+    fenced: true,
+    attributes,
+    keyLines,
+    body: lines.slice(close + 1).join('\n'),
+    bodyLine: close + 2,
+  }
+}
+
+function unquote(value) {
+  const quoted =
+    (value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))
+  return quoted && value.length >= 2 ? value.slice(1, -1) : value
+}
+
+/** Line of the first match, for findings that point into the body. */
+export function lineOf(text, needle, fallback = 1) {
+  const index = text.indexOf(needle)
+  if (index === -1) return fallback
+  return text.slice(0, index).split('\n').length
+}
+
+/** Column of the first match on its line, 1-based. */
+export function colOf(text, needle, fallback = 1) {
+  const index = text.indexOf(needle)
+  if (index === -1) return fallback
+  const lineStart = text.lastIndexOf('\n', index) + 1
+  return index - lineStart + 1
+}