@standardagents/code-plugin-sdk 1.0.0-alpha.0 → 1.0.0-alpha.1

package/README.md

@@ -54,6 +54,89 @@ Plugins retain Node access to files, networking and subprocesses under the user'
 Worker threads provide JavaScript fault isolation.
 Memory exhaustion outside V8 limits and native crashes can affect the runner process.
 
+## Collections
+
+A plugin installs from a Git repository or an npm package. One source holds
+one plugin or a collection of plugins.
+
+A collection lists its plugins in `standard-plugins.json` at the root of the
+repository or package:
+
+```json
+{
+  "schema": 1,
+  "plugins": [
+    { "id": "builds-monitor", "path": "builds-monitor" },
+    { "id": "pong", "path": "games/pong" }
+  ]
+}
+```
+
+`schema` is `1`. `plugins` holds 1 to 256 entries. Each `id` follows the
+plugin id pattern of the manifest and equals the `standardPlugin.id` in that
+entry's `package.json`. Each `path` is a relative POSIX path of at most 512
+characters with no leading slash, no backslash, and no empty, `.`, or `..`
+segment. Ids and paths are unique within one collection. An installer
+selects one entry with `--plugin <id>`.
+
+A root without `standard-plugins.json` is a single plugin when its
+`package.json` carries a valid `standardPlugin` manifest. Discovery treats it
+as one entry at path `""`.
+
+`validateCollection(value)` checks a parsed collection file and returns a
+frozen `PluginCollection`. `resolveCollection({ collection, packageJson })`
+applies the single-plugin fallback. `COLLECTION_FILE` names the file.
+
+## Dependencies
+
+A plugin with `dependencies` or `optionalDependencies` ships a lockfile
+beside its `package.json`, so every machine installs the same dependency
+tree. The installer refuses a plugin with dependencies and no lockfile.
+
+For an npm package the lockfile is `npm-shrinkwrap.json`. npm never
+publishes `package-lock.json`; `npm shrinkwrap` converts an existing
+`package-lock.json` into `npm-shrinkwrap.json`, and npm includes that file
+when it publishes the package. For a Git repository either
+`package-lock.json` or `npm-shrinkwrap.json` satisfies the rule.
+
+The SDK belongs under `peerDependencies`, with a `devDependencies` copy for
+the plugin's own tests. Inside Standard Code the bundled runtime supplies it.
+
+`lockfileRequirement({ packageJson, sourceKind })` returns whether the rule
+applies and which lockfile names satisfy it for `"npm"` or `"git"`.
+`checkPackageForPublish({ packageJson, files })` reports problems as
+`{ code, message }` objects: a missing lockfile, the SDK under
+`dependencies`, a missing peer declaration, a missing or invalid manifest, an
+entry outside the package files, or an id that differs from the collection
+entry. Both helpers are pure; they read no files.
+
+In a collection, each plugin directory holds its own `package.json` and its
+own lockfile.
+
+## Publishing a plugin
+
+The package installs a `standard-plugin` command for authoring.
+
+```sh
+npx standard-plugin check
+npx standard-plugin pack
+npm publish
+```
+
+`check [dir] [--source npm|git]` reads `package.json`, the optional
+`standard-plugins.json`, every collection entry's `package.json`, and the
+lockfiles. It prints each problem as `<path>: <code>: <message>` and exits
+with status 1 when it finds one. `--source git` applies the Git lockfile
+rule; the default is `npm`.
+
+`pack [dir]` runs `check`. When a plugin has dependencies and no
+`npm-shrinkwrap.json`, it runs `npm shrinkwrap`, which converts
+`package-lock.json`, and asks you to commit the new file. It then runs
+`npm pack --dry-run` and prints the files that npm will publish.
+
+The command is authoring tooling. The SDK entry never imports it, and a
+plugin never depends on it at run time.
+
 ## Testing
 
 `@standardagents/code-plugin-sdk/testing` exports `createHarness`.
@@ -66,7 +149,8 @@ The harness starts no subprocesses.
 ## Supported interface
 
 The public interface is the package's default export, its `testing` export,
-and the declarations in `src/index.d.ts` and `src/testing.d.ts`.
+the declarations in `src/index.d.ts` and `src/testing.d.ts`, and the
+`standard-plugin` command's `check` and `pack` behavior.
 
 The harness records the frames that the SDK runtime exchanges with its host,
 and `harness.receive` accepts such a frame. That wire protocol between the

package/bin/standard-plugin.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// Authoring tool for plugin packages. The SDK entry never imports this file.
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { COLLECTION_FILE, PluginError, checkPackageForPublish, validateCollection } from '../src/index.mjs'
+
+const USAGE = `usage: standard-plugin check [dir] [--source npm|git]
+       standard-plugin pack [dir]
+
+check  validates package.json, ${COLLECTION_FILE}, each collection entry, and lockfiles
+pack   runs check, creates npm-shrinkwrap.json when dependencies need one, then runs npm pack --dry-run`
+const IGNORED_DIRECTORIES = new Set(['node_modules', '.git'])
+const FILE_LIMIT = 50000
+
+function readJson(path) {
+  let text
+  try { text = readFileSync(path, 'utf8') } catch (error) {
+    if (error.code === 'ENOENT') return undefined
+    throw error
+  }
+  return JSON.parse(text)
+}
+
+/** Relative POSIX paths of regular files under root, without following links. */
+function listFiles(root) {
+  const files = []
+  const pending = ['']
+  while (pending.length) {
+    const directory = pending.pop()
+    for (const entry of readdirSync(join(root, directory), { withFileTypes: true })) {
+      const path = directory ? `${directory}/${entry.name}` : entry.name
+      if (entry.isDirectory()) { if (!IGNORED_DIRECTORIES.has(entry.name)) pending.push(path) }
+      else if (entry.isFile()) files.push(path)
+      if (files.length > FILE_LIMIT) throw new Error(`More than ${FILE_LIMIT} files under ${root}`)
+    }
+  }
+  return files
+}
+
+function tryJson(root, name, problems, location) {
+  try { return readJson(join(root, name)) } catch (error) {
+    problems.push({ location, code: 'invalid_json', message: `${name}: ${error.message}` })
+    return undefined
+  }
+}
+
+function collect(problems, location, list) {
+  for (const problem of list) problems.push({ location, ...problem })
+}
+
+/** Checks one source directory. Returns problems with the directory each one belongs to. */
+function checkDirectory(root, { sourceKind = 'npm' } = {}) {
+  const problems = []
+  const files = listFiles(root)
+  const packageJson = tryJson(root, 'package.json', problems, '.')
+  const collectionInput = tryJson(root, COLLECTION_FILE, problems, '.')
+  if (collectionInput === undefined) {
+    if (packageJson === undefined) problems.push({ location: '.', code: 'package_missing', message: `package.json or ${COLLECTION_FILE} is required` })
+    else collect(problems, '.', checkPackageForPublish({ packageJson, files, sourceKind }))
+    return problems
+  }
+  let collection
+  try { collection = validateCollection(collectionInput) } catch (error) {
+    if (!(error instanceof PluginError)) throw error
+    problems.push({ location: '.', code: error.code, message: `${COLLECTION_FILE}: ${error.message}` })
+    return problems
+  }
+  if (packageJson !== undefined) collect(problems, '.', checkPackageForPublish({ packageJson, files, sourceKind, requireManifest: false }))
+  else if (sourceKind === 'npm') problems.push({ location: '.', code: 'package_missing', message: 'an npm package needs a root package.json' })
+  for (const entry of collection.plugins) {
+    const entryPackage = tryJson(join(root, entry.path), 'package.json', problems, entry.path)
+    if (entryPackage === undefined) {
+      if (!problems.some(problem => problem.location === entry.path)) {
+        problems.push({ location: entry.path, code: 'package_missing', message: `collection entry ${entry.id} has no package.json` })
+      }
+      continue
+    }
+    const prefix = `${entry.path}/`
+    const entryFiles = files.filter(file => file.startsWith(prefix)).map(file => file.slice(prefix.length))
+    collect(problems, entry.path, checkPackageForPublish({ packageJson: entryPackage, files: entryFiles, sourceKind, expectedId: entry.id }))
+  }
+  return problems
+}
+
+function report(problems) {
+  for (const problem of problems) console.log(`${problem.location}: ${problem.code}: ${problem.message}`)
+  console.log(problems.length ? `${problems.length} problem${problems.length === 1 ? '' : 's'}` : 'ok')
+}
+
+function npm(args, cwd) {
+  const result = spawnSync('npm', args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' })
+  if (result.error) throw result.error
+  return result.status ?? 1
+}
+
+function parse(argv) {
+  const [command, ...rest] = argv
+  const options = { directory: '.', sourceKind: 'npm' }
+  for (let index = 0; index < rest.length; index++) {
+    const argument = rest[index]
+    if (argument === '--source') {
+      options.sourceKind = rest[++index]
+      if (!['npm', 'git'].includes(options.sourceKind)) throw new Error('--source takes npm or git')
+    } else if (argument.startsWith('-')) throw new Error(`unknown option ${argument}`)
+    else options.directory = argument
+  }
+  return { command, ...options, directory: resolve(options.directory) }
+}
+
+function check(options) {
+  const problems = checkDirectory(options.directory, options)
+  report(problems)
+  return problems.length ? 1 : 0
+}
+
+function pack(options) {
+  if (options.sourceKind !== 'npm') throw new Error('pack checks an npm package; --source git does not apply')
+  let problems = checkDirectory(options.directory, options)
+  const missing = problems.filter(problem => problem.code === 'lockfile_missing')
+  for (const problem of missing) {
+    const directory = resolve(options.directory, problem.location)
+    if (!existsSync(join(directory, 'package-lock.json'))) {
+      console.log(`${problem.location}: run npm install first so npm shrinkwrap has a package-lock.json to convert`)
+      continue
+    }
+    console.log(`${problem.location}: creating npm-shrinkwrap.json from package-lock.json`)
+    const status = npm(['shrinkwrap'], directory)
+    if (status !== 0) return status
+    console.log(`${problem.location}: commit npm-shrinkwrap.json; npm publishes it with the package`)
+  }
+  if (missing.length) problems = checkDirectory(options.directory, options)
+  report(problems)
+  if (problems.length) return 1
+  return npm(['pack', '--dry-run'], options.directory)
+}
+
+function main(argv) {
+  let options
+  try { options = parse(argv) } catch (error) { console.error(error.message); console.error(USAGE); return 2 }
+  try {
+    if (options.command === 'check') return check(options)
+    if (options.command === 'pack') return pack(options)
+  } catch (error) { console.error(`standard-plugin: ${error.message}`); return 2 }
+  console.error(USAGE)
+  return 2
+}
+
+process.exitCode = main(process.argv.slice(2))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/code-plugin-sdk",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.1",
   "type": "module",
   "description": "Standard Code plugin authoring SDK",
   "license": "MIT",
@@ -15,6 +15,7 @@
     ".": { "types": "./src/index.d.ts", "import": "./src/index.mjs" },
     "./testing": { "types": "./src/testing.d.ts", "import": "./src/testing.mjs" }
   },
-  "files": ["src", "README.md", "LICENSE"],
+  "bin": { "standard-plugin": "./bin/standard-plugin.mjs" },
+  "files": ["src", "bin", "README.md", "LICENSE"],
   "scripts": { "test": "node --test test/*.test.mjs" }
 }

package/src/index.d.ts

@@ -262,3 +262,49 @@ export interface PluginDefinition {
 export function definePlugin(definition: PluginDefinition): Readonly<PluginDefinition>;
 export function validateManifest(value: unknown): Readonly<PluginManifest>;
 export class PluginError extends Error { code: string; constructor(code: string, message: string) }
+
+/** One plugin inside a collection. The path is relative to the source root. */
+export interface PluginCollectionEntry {
+  id: string;
+  /** Relative POSIX path; "" names the source root for a single-plugin source. */
+  path: string;
+}
+/** The standard-plugins.json file at the root of a repository or npm package. */
+export interface PluginCollection {
+  schema: 1;
+  plugins: PluginCollectionEntry[];
+}
+/** File name of the collection manifest: standard-plugins.json. */
+export const COLLECTION_FILE: 'standard-plugins.json';
+export function validateCollection(value: unknown): Readonly<PluginCollection>;
+/** A collection file wins; without one, a valid package manifest makes the root one plugin at path "". */
+export function resolveCollection(source: { collection?: unknown; packageJson?: unknown }): Readonly<PluginCollection>;
+
+export type SourceKind = 'git' | 'npm';
+export type LockfileName = 'package-lock.json' | 'npm-shrinkwrap.json';
+export interface LockfileRequirement {
+  /** True when the package declares dependencies or optionalDependencies. */
+  required: boolean;
+  dependencies: readonly string[];
+  /** Lockfile names that satisfy the rule for this source kind. */
+  lockfiles: readonly LockfileName[];
+}
+/** Package name of this SDK, which a plugin lists under peerDependencies. */
+export const SDK_PACKAGE: '@standardagents/code-plugin-sdk';
+export function lockfileRequirement(input: { packageJson: unknown; sourceKind: SourceKind }): LockfileRequirement;
+export interface PublishProblem {
+  code: 'invalid_package' | 'package_private' | 'lockfile_missing' | 'sdk_dependency' | 'sdk_peer_missing' |
+    'manifest_missing' | 'invalid_manifest' | 'invalid_payload' | 'payload_too_large' | 'incompatible_version' |
+    'entry_missing' | 'id_mismatch';
+  message: string;
+}
+/** Pure checks over a package.json and the relative paths of the files that ship with it. */
+export function checkPackageForPublish(input: {
+  packageJson: unknown;
+  files: readonly string[];
+  sourceKind?: SourceKind;
+  /** False for a collection root whose package.json carries no plugin manifest. */
+  requireManifest?: boolean;
+  /** The collection entry id the manifest must match. */
+  expectedId?: string;
+}): readonly PublishProblem[];

package/src/index.mjs

@@ -1,6 +1,10 @@
 import { ensure, identifier, validateManifest, PluginError } from './manifest.mjs'
+import { COLLECTION_FILE, resolveCollection, validateCollection } from './collection.mjs'
+import { SDK_PACKAGE, checkPackageForPublish, lockfileRequirement } from './publish.mjs'
 
 export { validateManifest, PluginError }
+export { COLLECTION_FILE, resolveCollection, validateCollection }
+export { SDK_PACKAGE, checkPackageForPublish, lockfileRequirement }
 
 export function definePlugin(definition) {
   ensure(definition && identifier(definition.id) && typeof definition.activate === 'function',

package/src/publish.mjs

@@ -0,0 +1,62 @@
+import { PluginError, ensure, object, validateManifest } from './manifest.mjs'
+
+export const SDK_PACKAGE = '@standardagents/code-plugin-sdk'
+export const SOURCE_KINDS = Object.freeze(['git', 'npm'])
+const LOCKFILES = Object.freeze({ git: Object.freeze(['package-lock.json', 'npm-shrinkwrap.json']), npm: Object.freeze(['npm-shrinkwrap.json']) })
+
+function names(section) { return object(section) ? Object.keys(section) : [] }
+
+/** Runtime dependencies are the ones npm installs for a consumer of the package. */
+export function runtimeDependencies(packageJson) {
+  ensure(object(packageJson), 'invalid_package', 'package.json must contain an object')
+  return [...new Set([...names(packageJson.dependencies), ...names(packageJson.optionalDependencies)])]
+}
+
+/**
+ * A plugin with runtime dependencies ships a lockfile. npm publishes
+ * npm-shrinkwrap.json and drops package-lock.json, so an npm source needs the
+ * shrinkwrap; a Git source may keep either file.
+ */
+export function lockfileRequirement({ packageJson, sourceKind }) {
+  ensure(SOURCE_KINDS.includes(sourceKind), 'invalid_source', 'Source kind must be git or npm')
+  const dependencies = runtimeDependencies(packageJson)
+  return Object.freeze({ required: dependencies.length > 0, dependencies: Object.freeze(dependencies), lockfiles: LOCKFILES[sourceKind] })
+}
+
+function normalize(path) { return path.replace(/^\.\//, '') }
+
+/**
+ * Pure publish checks for one plugin directory. `files` lists the relative
+ * POSIX paths that ship with the package. Returns a list of problems; an empty
+ * list means the package passes.
+ */
+export function checkPackageForPublish({ packageJson, files, sourceKind = 'npm', requireManifest = true, expectedId } = {}) {
+  ensure(Array.isArray(files) && files.every(file => typeof file === 'string'), 'invalid_source', 'files must list relative paths')
+  const problems = []
+  const problem = (code, message) => problems.push(Object.freeze({ code, message }))
+  if (!object(packageJson)) return Object.freeze([Object.freeze({ code: 'invalid_package', message: 'package.json must contain an object' })])
+  const present = new Set(files.map(normalize))
+  if (packageJson.private === true && sourceKind === 'npm') problem('package_private', 'package.json marks the package private, so npm refuses to publish it')
+  const requirement = lockfileRequirement({ packageJson, sourceKind })
+  if (requirement.required && !requirement.lockfiles.some(name => present.has(name))) {
+    problem('lockfile_missing', `Dependencies (${requirement.dependencies.join(', ')}) need ${requirement.lockfiles.join(' or ')} beside package.json`)
+  }
+  for (const section of ['dependencies', 'optionalDependencies']) {
+    if (names(packageJson[section]).includes(SDK_PACKAGE)) problem('sdk_dependency', `${SDK_PACKAGE} belongs under peerDependencies, not ${section}`)
+  }
+  let manifest = null
+  if (packageJson.standardPlugin === undefined) {
+    if (requireManifest) problem('manifest_missing', 'package.json has no standardPlugin manifest')
+  } else {
+    try { manifest = validateManifest(packageJson.standardPlugin) } catch (error) {
+      if (!(error instanceof PluginError)) throw error
+      problem(error.code, error.message)
+    }
+  }
+  if (manifest) {
+    if (!names(packageJson.peerDependencies).includes(SDK_PACKAGE)) problem('sdk_peer_missing', `${SDK_PACKAGE} must be listed under peerDependencies`)
+    if (!present.has(normalize(manifest.entry))) problem('entry_missing', `Entry ${manifest.entry} is not among the package files`)
+    if (expectedId !== undefined && manifest.id !== expectedId) problem('id_mismatch', `Manifest id ${manifest.id} differs from collection entry ${expectedId}`)
+  }
+  return Object.freeze(problems)
+}