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

package/README.md

@@ -11,8 +11,8 @@ Its `package.json` includes a static `standardPlugin` manifest.
 {
   "name": "example-status",
   "type": "module",
-  "peerDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.0" },
-  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.0" },
+  "peerDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.10-rows.0" },
+  "devDependencies": { "@standardagents/code-plugin-sdk": "^1.0.0-alpha.10-rows.0" },
   "standardPlugin": {
     "apiVersion": 1,
     "id": "example-status",
@@ -44,6 +44,20 @@ package, such as `@standardagents/code-plugin-sdk/testing`, are refused when
 the plugin runs inside Standard Code. The `testing` export serves the
 plugin's own test suite.
 
+The complete rendering contract is in [REFERENCE.md](./REFERENCE.md). It
+covers rows, styled text, badges, cards, slots, panels, overlays, host-rendered
+views, ANSI canvases, styled canvas hover text, input focus,
+popover/column/pane presentations, remote read-only behavior, and the frontend
+surfaces that are still planned.
+
+Plugin source imports the default package entry. Plugin tests may import
+`@standardagents/code-plugin-sdk/testing` for `createHarness`. Runner internals,
+raw host request envelopes, and internal module paths are outside the public
+package exports. First-party plugins use these same public entries and receive
+the same manifest validation, capability checks, request bounds, and remote
+ownership rules as third-party plugins. A plugin ID does not grant a host
+operation or fetch exception.
+
 The runtime disposes publishers, subscriptions, schedules and pending requests.
 Plugins register additional cleanup through `ctx.onDispose` or an activation return value.
 Handlers receive an abort signal.
@@ -54,6 +68,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`.
@@ -65,8 +162,9 @@ 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 public interface is the package root export, its `testing` export,
+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
@@ -77,15 +175,92 @@ without notice. Plugin code and plugin tests should treat recorded frames as
 opaque values and drive the plugin through `PluginContext` and the harness
 methods.
 
-Local `ctx.state` belongs to one machine.
+`ctx.state` is per-plugin key and value storage. Standard Code stores these
+values in the user's account, so every machine the user has reads and writes
+the same keys. `ctx.state.keys()` returns the sorted key names for this
+plugin's account namespace. It returns an empty array when the plugin has no
+keys and accepts only `RequestOptions`; it has no prefix or pagination
+arguments. Another plugin cannot read these keys, even when it uses the same
+account. Key names are 1 to 128 bytes. The first character is ASCII
+alphanumeric or `_`; later characters are ASCII alphanumeric, `_`, `.`, `:`,
+or `-`. A plugin holds at most 256 keys, and one value is at most 64 KiB of
+JSON. The host applies the same account authority and revocation checks to
+`keys()` as it applies to `get()` and `set()`.
 The public context declarations are in `src/index.d.ts`.
 
 ## Releases
 
 The Standard Code build workflow publishes this package when the version in
-`package.json` changes. Prereleases publish under the `next` dist-tag and
-releases under `latest`.
+`package.json` changes. Main prereleases publish under `next` and main releases
+under `latest`. Feature branches publish under their product branch tag. Authors
+can install a published prerelease by its exact version.
+
+## Sidebar card titles
+
+Sidebar card titles use muted, regular-weight text. A card declaration may
+supply an `icon` containing one Nerd Font private-use glyph, for example
+`"icon": "\uDB81\uDCC5"` (a gauge). The author chooses the card's topic icon.
+The host shows it only on the viewer's Nerd Font tier. Other tiers omit the
+icon and its spacing. Omitted icons have no fallback. This applies to bordered
+and borderless cards. Empty titles remain empty.
+
+A card view may replace its declared title through
+`ui.view(root, { title: [{ text: 'Builds ' }, { text: '●', foreground: 'green' }] })`.
+The optional `title` uses native `TextSpan` fields, including `#RRGGBB` and the terminal colors `black`, `red`, `green`,
+`yellow`, `blue`, `magenta`, `cyan`, and `white`;
+`ui.span()` is a body-view builder with a different shape. Titles accept 1–32
+passive spans and at most 512 UTF-8 bytes of combined, nonblank single-line text.
+Actions, control characters, and bidi formatting are rejected. Each replacement
+updates the body and title together. Omitting `title` restores the manifest title.
+This option belongs to card views. Plugins own the meaning and color of any
+status light; the SDK adds no health indicator. Host title styling and supported
+author-selected Nerd Font icons apply around the author-supplied spans.
 
 ## License
 
 MIT. See `LICENSE`.
+
+## Responsive pane rows
+
+A pane header or footer slot can publish `rows` containing a `layout` and empty
+`spans`. `layout.fields` is an ordered list of passive text fields. The host
+resolves its geometry separately for every viewer, including pane resizes.
+No resize event or producer repaint is needed.
+
+```js
+slot.replace({ kind: 'rows', rows: [{ id: 'status', spans: [], layout: {
+  projectTint: true,
+  fields: [
+    { text: 'org/repo', bold: true },
+    { text: '~/src/repo', gap: 2, flex: true, tone: 'muted',
+      shrink: { priority: 1, min: 8, mode: 'middle' } },
+    { text: ' +24 ', gap: 2, flex: true, tone: 'ok', surface: true },
+    { text: ' −6 ', tone: 'error', surface: true },
+  ],
+} }] })
+```
+
+`gap` reserves 0–8 cells before a field. `flex` distributes spare width across
+marked gaps; related fields without flexible gaps stay together. The first
+field starts at the left edge and the final field reaches the right edge when
+at least one visible flexible gap exists. `projectTint` fills the whole row
+with the pane project's identity tint. `tone` accepts `muted`, `ok`, `error`,
+`info`, `warning`, or `project`; semantic colors resolve against the viewer's
+terminal palette. `surface` shades that field's background and `bold` emphasizes
+its text. Include spaces in a field for padded color blocks.
+
+`icon` is one Nerd Font private-use glyph. `fallback` is an optional ASCII
+replacement (up to 16 bytes); viewers without Nerd Font support use the fallback.
+The host supplies one space after an icon or fallback.
+
+`shrink` policies run by increasing `priority` (0–255), then field order.
+`min` is the retained text width in cells. `start`, `middle`, and `end` select
+where an ellipsis replaces removed text. `hide` removes a field including its
+icon and gap; all hide policies with equal priority are removed together.
+Trimming preserves grapheme boundaries. If the declared minimum widths still
+exceed the pane, remaining content clips at the right edge.
+
+Layouts allow 1–32 fields, 2,048 UTF-8 bytes per text field and 8,192 total text
+bytes. Controls and bidi formatting characters are rejected. Layouts are
+supported only in pane header/footer slots. Ordinary rows and full/half slot
+stacking retain their existing behavior.