pocketbase/pocketbase

Can another program use it through a documented, machine-readable surface?

• next: [service] L2 A contract exists: a checked-in OpenAPI/GraphQL/protobuf/AsyncAPI spec, a framework-generated spec, MCP tool schemas, or a standard application protocol that off-the-shelf clients speak (RESP, MQTT, gRPC, PostgreSQL wire, …). (no machine-readable contract)
• next: [cli] L1 Invocable non-interactively: no prompts, or prompts guarded by a TTY check or a --yes/--no-input option. (prompts without a non-TTY guard: ui/src/fields/bool/input.js, ui/src/fields/date/input.js, ui/src/fields/editor/input.js)
• next: [library] L4 An API reference is generated from the code (autodoc, mkdocstrings, typedoc, …). (no generated API reference)

cli ladder · level 0

• ✗ L1 Invocable non-interactively: no prompts, or prompts guarded by a TTY check or a --yes/--no-input option. prompts without a non-TTY guard: ui/src/fields/bool/input.js, ui/src/fields/date/input.js, ui/src/fields/editor/input.js
• ✓ L2 --help documents every option (at least 90% of options have help text). pocketbase.go 6 matches
• ✗ L3 Machine-readable output (--json/--format) and documented exit statuses. no --json/--format option
• ✗ L4 The output format is specified by a JSON Schema. no JSON Schema for the output

library ladder · level 3

• ✓ L1 An importable, packaged API exists. go.mod Go module with exported packages
• ✓ L2 The public API is delimited (__all__, an exports map, exported identifiers). go.mod exported identifiers
• ✓ L3 The public API is statically typed (py.typed, type declarations, a typed language). go.mod statically typed language
• ✗ L4 An API reference is generated from the code (autodoc, mkdocstrings, typedoc, …). no generated API reference

service ladder · level 1

• ✓ L1 A network surface exists: HTTP routes, an MCP server, or a standard protocol listener. apis/record_auth.go go-http: 96 route declarations
• ✗ L2 A contract exists: a checked-in OpenAPI/GraphQL/protobuf/AsyncAPI spec, a framework-generated spec, MCP tool schemas, or a standard application protocol that off-the-shelf clients speak (RESP, MQTT, gRPC, PostgreSQL wire, …). no machine-readable contract
• ✗ L3 A contract covers its transport: an HTTP contract covers at least 80% of declared routes (generated contracts do), or the application layer over a standard protocol (commands, topics, payloads) is specified in a protocol document or AsyncAPI. no contract
• ✗ L4 A second surface: another transport (HTTP and a protocol, two protocols), an MCP server, a CLI with JSON output, or an SDK. only one programmatic surface

Can integrators rely on it not changing under them?

• next: L3 A deprecation mechanism is used in code (warnings, @deprecated, Deprecation/Sunset headers) or the API is versioned. (no deprecation mechanism or API versioning)

all ladder · level 2

• ✓ L1 Releases are versioned (semver tags or versioned changelog sections). 294 semver tags, latest v0.22.56
• ✓ L2 A changelog exists and marks breaking changes. CHANGELOG.md marks breaking changes
• ✗ L3 A deprecation mechanism is used in code (warnings, @deprecated, Deprecation/Sunset headers) or the API is versioned. no deprecation mechanism or API versioning
• ✓ L4 Across tagged releases, no OpenAPI operation, CLI option or __all__ symbol was removed without first being deprecated. 20 tagged releases compared

Can others react to state changes without polling?

• next: L3 Signed webhooks registrable through the API, or two mechanisms (webhooks, streams, a broker). (one delivery mechanism, or webhooks that are unsigned or not registrable through the API)

service ladder · level 2

• ✓ L1 Internal events exist (signals, queues, an outbox, emitters). apis/realtime.go 1 match
• ✓ L2 Webhooks sent by this system, or a streaming endpoint (SSE, WebSocket). apis/realtime.go 1 match
• ✗ L3 Signed webhooks registrable through the API, or two mechanisms (webhooks, streams, a broker). one delivery mechanism, or webhooks that are unsigned or not registrable through the API
• ✗ L4 Events are described by AsyncAPI or CloudEvents. no AsyncAPI or CloudEvents contract

Can a machine act with its own revocable, least-privilege identity?

• next: [service] L2 Per-client, revocable credentials (managed API keys, service accounts) or OAuth2. (no managed keys or OAuth)
• next: [cli] L4 Several profiles or scoped credentials per target. (no credential profiles)
• next: [library] L4 Several profiles or scoped credentials per target. (no credential profiles)

cli ladder · level 3

• ✓ L1 Credentials can be supplied non-interactively (environment variables). tools/auth/oidc.go 1 match
• ✓ L2 Credentials never need to be on the command line, and their environment variables are documented. CHANGELOG_23_39.md 2 matches
• ✓ L3 No output or log statement includes a credential. no credential in print/log statements
• ✗ L4 Several profiles or scoped credentials per target. no credential profiles

library ladder · level 3

• ✓ L1 Credentials can be supplied non-interactively (environment variables). tools/auth/oidc.go 1 match
• ✓ L2 The credential environment variables are documented. CHANGELOG_23_39.md 2 matches
• ✓ L3 No output or log statement includes a credential. no credential in print/log statements
• ✗ L4 Several profiles or scoped credentials per target. no credential profiles

service ladder · level 1

• ✓ L1 Programmatic authentication (bearer tokens, API keys). go.mod 1 matchcore/record_tokens.go 1 match
• ✗ L2 Per-client, revocable credentials (managed API keys, service accounts) or OAuth2. no managed keys or OAuth
• ✓ L3 Credentials carry scopes or permissions. tools/auth/base_provider.go 3 matchestools/auth/gitee.go 3 matches
• ✓ L4 Standard provisioning or federation (OIDC client credentials, SCIM). tools/auth/oidc.go 9 matchesui/src/collections/collectionChangesConfirmationModal.js 7 matches

Can its data get in and out, in bulk, in open formats, with an explicit schema?

all ladder · level 4

• ✓ L1 The data schema is explicit (migrations, DDL, schema files). migrations/1640988000_aux_init.gomigrations/1640988000_init.go
• ✓ L2 An export exists (endpoint or command, not only the UI). apis/backup.go 4 matchesapis/backup_create.go 1 match
• ✓ L3 A bulk export in an open format, and a bulk import. ui/src/mimeTypes.js 6 matchesapis/backup.go 1 match
• ✓ L4 The export format is documented and the round trip is tested. CHANGELOG_16_22.md 2 matchesCHANGELOG_23_39.md 2 matches

Can an automated caller use it without guessing, and recover from failure?

• next: [service] L2 Field-level validation errors, and paginated lists. (no request validation)
• next: [cli] L1 Never blocks on a prompt when stdin is not a TTY. (prompts without a non-TTY guard: ui/src/fields/bool/input.js, ui/src/fields/date/input.js, ui/src/fields/editor/input.js)
• next: [library] L1 Errors are specific exception types, and library code never calls sys.exit. (no exception classes)

cli ladder · level 0

• ✗ L1 Never blocks on a prompt when stdin is not a TTY. prompts without a non-TTY guard: ui/src/fields/bool/input.js, ui/src/fields/date/input.js, ui/src/fields/editor/input.js
• ✓ L2 Data on stdout, diagnostics on stderr, non-zero exit on failure. plugins/jsvm/internal/types/types.go 3 matchestools/filesystem/blob/bucket.go 2 matches
• ✗ L3 Documented exit statuses distinguish error classes, errors are JSON in JSON mode, and color is off when not a TTY. exit statuses aren't documented
• ✗ L4 --dry-run, limits for long or costly operations (timeouts, budgets), and agent docs. no --dry-run

library ladder · level 0

• ✗ L1 Errors are specific exception types, and library code never calls sys.exit. no exception classes
• ✓ L2 Inputs are validated with messages naming the bad argument. ui/src/router.js 3 matchesui/src/base/leaflet.js 1 match
• ✗ L3 Timeouts and retries are configurable. no retry parameter
• ✗ L4 Agent docs, and examples that run as tests (doctests). no agent docs

service ladder · level 1

• ✓ L1 Errors are machine-readable: consistent JSON over HTTP, or a standard protocol's native error replies (RESP errors, MQTT reason codes, gRPC status, SQLSTATE). ui/src/base/tinymce.js 3 matches
• ✗ L2 Field-level validation errors, and paginated lists. no request validation
• ✗ L3 Typed errors (RFC 9457 over HTTP, or a standard protocol's typed error codes), idempotent writes (Idempotency-Key), and rate-limit signals. no typed errors
• ✗ L4 Dry-run or validate-only, conditional requests, and agent docs. no agent docs

Can another system run and compose it without a human?

• next: [service] L2 Configured through environment variables, documented: a .env example, a config schema, or docs naming at least half of the variables the code reads. (the environment variables aren't documented)
• next: [cli] L3 Published to a public registry and run non-interactively in CI. (the command isn't run in CI)
• next: [library] L4 Optional features behind extras/features. (no optional extras)

cli ladder · level 2

• ✓ L1 Runnable from source (a declared entry point). plugins/jsvm/internal/types/types.go go main
• ✓ L2 Installable as a package that provides the command. plugins/jsvm/internal/types/types.go go main
• ✗ L3 Published to a public registry and run non-interactively in CI. the command isn't run in CI
• ✓ L4 Also shipped as a container image or a single binary. .goreleaser.yaml

library ladder · level 3

• ✓ L1 Importable from source. go.mod Go module with exported packages
• ✓ L2 Installable as a package (a package manifest). go.mod package manifest
• ✓ L3 Published to a public registry, with at most 10 runtime dependencies. .github/workflows/release.yaml 8 matches 2 runtime dependencies
• ✗ L4 Optional features behind extras/features. no optional extras

service ladder · level 1

• ✓ L1 Runnable from source with documented steps (a README with commands). README.md
• ✗ L2 Configured through environment variables, documented: a .env example, a config schema, or docs naming at least half of the variables the code reads. the environment variables aren't documented
• ✗ L3 A container image. no Dockerfile
• ✗ L4 Composition artifacts (compose, Helm, IaC). no compose/Helm/IaC

Can behaviour be added without modifying the code?

• next: L1 Internal seams: a registry, registration function or plugin manager. (no registry or registration function)

all ladder · level 0

• ✗ L1 Internal seams: a registry, registration function or plugin manager. no registry or registration function
• ✗ L2 The docs show how to add behaviour through those seams (even in-tree). no registration functions to document
• ✗ L3 Out-of-tree extensions are discovered (entry points, a plugin directory, configuration) without editing the package. extensions must be added inside the package
• ✗ L4 The extension API is versioned, has lifecycle hooks, and has example extensions. the extension API isn't versioned

Can an operator, or an orchestrating agent, tell whether it works and why not?

• next: [service] L2 Structured logs. (no structured logging)
• next: [cli] L2 Verbosity control for diagnostics (--quiet, --log-level, --debug). (no --quiet or log-level control)
• next: [library] L1 Logs through a standard logger namespace and never prints from library code. (library code prints: plugins/jsvm/internal/types/generated/types.d.ts)

cli ladder · level 1

• ✓ L1 Meaningful exit statuses, and errors on stderr. plugins/jsvm/internal/types/types.go 3 matchestools/filesystem/blob/bucket.go 2 matches
• ✗ L2 Verbosity control for diagnostics (--quiet, --log-level, --debug). no --quiet or log-level control
• ✗ L3 Structured logs (e.g. --log-format json) or a machine-readable run summary. no structured diagnostics
• ✗ L4 Tracing hooks (OpenTelemetry). no tracing hooks

library ladder · level 0

• ✗ L1 Logs through a standard logger namespace and never prints from library code. library code prints: plugins/jsvm/internal/types/generated/types.d.ts
• ✗ L2 Log levels are used meaningfully (at least two levels). fewer than two log levels used
• ✗ L3 Optional metrics or tracing hooks. no metrics or tracing hooks
• ✗ L4 OpenTelemetry instrumentation available. no OpenTelemetry instrumentation

service ladder · level 1

• ✓ L1 A health or readiness endpoint, or a container healthcheck. apis/health.go 1 match
• ✗ L2 Structured logs. no structured logging
• ✗ L3 Metrics. no metrics
• ✗ L4 Distributed tracing (OpenTelemetry). no tracing

Can an agent change it safely with limited context?

• next: L3 At least 90% of modules fit 32k tokens and no file exceeds 12k; test/source token ratio at least 0.3; at least 70% of the code is typed. (90% of modules fit 32k tokens; 5 files over 12k; 65% of code is typed (< 70%))

all ladder · level 2

• ✓ L1 A README and some tests. README.mdapis/backup_test.go 195 test files
• ✓ L2 CI runs the tests; applications pin dependencies (libraries and zero-dependency projects are exempt). .github/workflows/release.yaml library or zero-dependency project: lockfile not required
• ✗ L3 At least 90% of modules fit 32k tokens and no file exceeds 12k; test/source token ratio at least 0.3; at least 70% of the code is typed. 90% of modules fit 32k tokens; 5 files over 12k; 65% of code is typed (< 70%)
• ✗ L4 No import cycles, and agent docs (AGENTS.md, CLAUDE.md, llms.txt). no agent docs (AGENTS.md, CLAUDE.md, llms.txt)