Installation

PermDock is in Phase 0. Nothing is published to npm yet; the commands below describe the intended install experience so that the docs, README and skills agree before the first release. See the roadmap for what ships in which phase.

Packages

pnpm add permdock
pnpm add -D @permdock/cli @permdock/testing

npm and yarn work the same way; the repository itself uses pnpm workspaces.

Requirements

• TypeScript 5.9, 6 or 7. The type tests in tests/types run against all three, and the public API avoids template-literal unions so TypeScript 7 stays fast. Permissions are typed object references, not string unions.
• ESM only. There is no CommonJS build. Your tsconfig.json needs a moduleResolution that understands package exports (bundler, node16 or nodenext) so subpath imports such as permdock/react resolve.
• A current Node.js LTS release for servers and the CLI. Browser and React Native bundles are produced from the same ESM entry points.
• Zero runtime dependencies in core. @standard-schema/spec is the only regular dependency and it is types only.

Runtimes

Core uses only the WinterTC Minimum Common API (fetch, Request, Response, URL, crypto.subtle, TextEncoder, structuredClone) and no Node built-ins, no AsyncLocalStorage, no module-level state. That is by construction (invariants 7 and 12 in AGENTS.md) and a conformance test in tests/bundle asserts it from Phase 1: every client entry and permdock/server must load in a bare WinterTC-shaped global. The table lists what each runtime adds or lacks; nothing in it changes how a decision is made.

The one runtime-specific caveat is state: any store or sink that defaults to memory (memoryApprovalStore, memorySink) is per process or per isolate and resets on cold start. permdock doctor warns when the memory store is the configured ApprovalStore in a serverless target. Recipes for Durable Objects, KV, Redis and Postgres stores live on the approvals and audit and observability pages; none is a package.

A Standard Schema validator

Resources are defined from any validator that implements Standard Schema. Bring the one you already use:

pnpm add zod      # or
pnpm add valibot  # or
pnpm add arktype

PermDock never imports a validator itself. resource(Post, ...) reads Post['~standard'] to infer the instance type and to validate untrusted input at trust boundaries (see validation). Boundary validation is synchronous, so a schema whose validate returns a Promise produces a typed PermDockValidationError instead of a silent deny.

Subpath exports

All adapters live in the one permdock package. Import only what a bundle needs; nothing from a server entry is reachable from a client entry.

The full matrix with example apps and related standards is on the adapters index.

Optional peers

Core has no runtime dependencies. A few entries verify material or talk to a vendor SDK and declare an optional peer instead of bundling it:

TypeScript configuration

A minimal tsconfig.json that works with the subpath exports and keeps inference fast:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "skipLibCheck": true
  }
}

strict matters: subject narrowing through assert and the actions / collection arity checks rely on strict null checks. The library itself is built with isolatedDeclarations and erasableSyntaxOnly, so its declaration files contain no inferred-only types and load quickly.

Where files go

The quick start fills in the first three.

Verify the install

pnpm permdock doctor

doctor checks the TypeScript version, module resolution, that exactly one copy of permdock is installed, that no server entry is imported from a client file, that memoryApprovalStore() is not the store in a serverless deployment that surfaces approvals, that PERMDOCK_CLOUD_* variables (when present) are server-only and reach the API, and that the catalog produced by permdock collect is fresh. It is the first thing the shipped wire-permdock skill runs.

Next steps

• Quick start: define, grant, check, guard.
• Larger apps: per-feature definitions, mergePermissions, permdock collect.
• Naming: why every adapter exports createPermDock.