ESM API

Use Presswork as an Effect service through its public ESM root export, with schemas, typed results, failures, and live Layer setup.

Presswork publishes one named ESM entry point from presswork. The public API exposes the Presswork Effect service, input and output schemas, and their TypeScript types. Package subpaths and workspace modules are not public API.

Run a Check

Install Presswork and the compatible Effect release in an ESM project running Node.js 24 or later. The example imports both packages directly.

npm install presswork effect@4.0.0-rc.115

This example discovers the Repository Root from the current directory and runs a Check.

import { Effect, Schema } from 'effect';
import { Presswork, RepositorySelection } from 'presswork';

const repository = Schema.decodeUnknownSync(RepositorySelection)({});

const report = await Effect.runPromise(
  Effect.gen(function* () {
    const presswork = yield* Presswork;
    return yield* presswork.check(repository);
  }).pipe(Effect.provide(Presswork.layer), Effect.scoped),
);

console.log(report);

RepositorySelection accepts an optional root. When it is omitted, Presswork discovers the Repository Root from the current directory. Presswork.layer supplies the live service implementation. The service methods return Effects with typed failure channels.

`Presswork`

Presswork is an Effect Context.Service. Access it with yield* Presswork inside an Effect program and provide Presswork.layer at the application boundary.

Method	Input	Success	Failure
`check(repository)`	`RepositorySelection`	`CheckReport`	`CheckFailure`
`listDocumentTypes(repository)`	`RepositorySelection`	`CreateCatalog`	`CheckFailure`
`create(request)`	`CreateRequest`	`CreateOutcome`	`CreateFailure`
`renderDocsSkill(repository)`	`RepositorySelection`	`string`	`RenderSkillDocsFailure`

check is read-only. create can initialize a Document Draft and update its Index Document according to the selected Document Type and Creation Policy. renderDocsSkill returns the complete generated SKILL.md content as a string.

Inputs

Use the exported Effect schemas to decode unknown values before passing them to the service.

Input	Field	Type	Required	Meaning
`RepositorySelection`	`root`	`string`	No	An explicit Repository Root selection.
`CreateRequestSchema`	`documentType`	`DocumentTypeId`	Yes	The Document Type to create.
`CreateRequestSchema`	`fields`	`DocumentFieldAssignment[]`	Yes	Field values used to render the draft.
`CreateRequestSchema`	`repository`	`RepositorySelection`	Yes	The Repository Root selection.
`DocumentFieldAssignmentSchema`	`name`	`DocumentFieldName`	Yes	The configured field name.
`DocumentFieldAssignmentSchema`	`value`	`string`	Yes	The field value.

DocumentTypeId is a branded schema for a lower-case identifier. DocumentFieldName is a branded string schema. The matching TypeScript exports are CreateRequest and DocumentFieldAssignment.

Results

check returns CheckReport. See Check Report for its complete and incomplete variants, fields, Violations, and Operational Diagnostics.

listDocumentTypes returns CreateCatalog through CreateCatalogSchema.

Field	Type	Required	Meaning
`repositoryRoot`	`string`	Yes	The selected absolute Repository Root.
`documentTypes`	array	Yes	The configured Document Types.
`documentTypes[].documentType`	`DocumentTypeId`	Yes	The Document Type identifier.
`documentTypes[].creationPolicy`	`external`, `manual`, or `presswork`	Yes	The owner of Document Creation.
`documentTypes[].externalWorkflow`	`string`	No	The configured external workflow, if present.

create returns CreateOutcome through CreateOutcomeSchema.

Field	Type	Meaning
`createdPath`	`string`	The created repository-relative path.
`updatedIndex`	`string`	The updated repository-relative Index Document path.
`draftStatus`	`"unfinished"`	The fixed status of a newly initialized Document Draft.
`pendingRequirements`	`string[]`	Template requirements that remain for the author to resolve.

renderDocsSkill returns the generated SKILL.md as a string.

The root API also exports OperationalDiagnosticSchema, DocumentDiscoveryDiagnosticSchema, and DocumentEvaluationDiagnosticSchema with their matching TypeScript types. Their fields and conditions are documented with the Check Report Operational Diagnostics.

Failure types

The root entry point exports CheckFailure, CreateFailure, RenderSkillDocsFailure, and their combined CommandFailure union. Failures remain in the Effect error channel.

Repository and configuration failures apply to all four methods.

`_tag`	Additional fields	Condition
`RepositoryRootNotFoundError`	`message`, `path`, `recovery`	Repository Root discovery found no valid root.
`InvalidRepositoryRootError`	`message`, `path`, `recovery`	An explicit root is not a valid Repository Root.
`RepositoryRootUnavailableError`	`cause`, `message`, `path`, `recovery`	Presswork could not inspect the selected Repository Root.
`ConfigurationUnavailableError`	`cause`, `message`, `path`, `recovery`	Present Presswork Configuration could not be read.
`InvalidConfigurationError`	`message`, `path`, `recovery`	Present Presswork Configuration is invalid.

create can also fail with _tag: "DocumentCreationError". It has code, message, and recovery, with optional path and cause fields.

`code`	Condition
`document-type-unknown`	The requested Document Type is not configured.
`document-type-creation-external`	An external workflow owns creation.
`document-type-creation-manual`	The Document Type requires manual creation.
`document-creation-field-invalid`	A field name or value does not satisfy the Document Type.
`document-creation-preflight-failed`	Template, index, or mutation preflight failed.
`document-creation-conflict`	An existing destination or another writer prevented creation.
`document-creation-index-stale`	The Index Document changed before publication.
`document-creation-recovery-required`	The Index update failed after the draft was preserved.
`document-creation-unavailable`	A required Template or filesystem operation was unavailable.

renderDocsSkill can also fail with _tag: "SkillDocsError". It has code, message, and recovery, with an optional path.

`code`	Condition
`document-discovery-unavailable`	Document discovery could not complete.
`document-read-unavailable`	A Recognized Document could not be read.
`target-inspection-unavailable`	A local Markdown target could not be inspected.
`skill-guidance-unavailable`	Required Template or Document Type guidance was unavailable.

Use Effect error operators to inspect or recover from these failures before running the program when your application needs custom handling.

Use the CLI reference for process behavior and the Check Report reference for the report fields and semantics.