dark-library

Files (1)

• SKILL.md

SKILL.md (first lines)

# Dark Library

Policy and scoped exceptions live in `AGENTS.md`. This skill describes how to
implement them. Start with new features; do not migrate existing modules or add
a template library. Bootstrap tooling only together with the first real library.

## Layout and naming

Name by capability (`geofilter`, `tilecache`), not feature/screen. Client names
are lowercase, one word or kebab-case; server names are one lowercase word,
matching the Go package name.

```text
src/client/dark/<name>/
  index.ts             public entry: re-exports + @packageDocumentation only
  *.ts, *.tsx          strict TypeScript implementation
  *.module.css         component styles
  store.ts             only react-redux integration (Redux libraries)
  *.test.ts(x)         public contract tests, imports from ./index only
  examples.test.ts(x)  public contract tests; never imported into README
  README.md            generated, committed, reviewed

src/server/dark/<name>/
  doc.go               package purpose and invariants
  *.go                 implementation
  *_test.go            package <name>_test; public API only
  example_test.go      Example functions with // Output:
  README.md            generated, committed, reviewed
```

Client public declarations live in implementation files and are re-exported
through `index.ts`. The remaining client stays JS. Never edit generated docs
directly; change doc comments or examples and regenerate.

## Isolation and no-mock contract

Allowed imports:
- Files in the same library.
- Another dark library's public entry: `../<other>/index` on client,
  `dekart/src/server/dark/<other>` on server.
- Third-party packages in `node_modules`, Go module dependencies and Go stdlib,
  subject to the deny list and no-mock rule below.

Forbidden dependencies and behavior:
- App files under `src/client` or `src/server` outside `dark/`, generated proto
  packages (including `dekart-proto`), app reducers/actions, `api.js`, `grpc`,
  tracking or app state. Reviewed glue maps proto objects to/from library types.
- Go imports: `os`, `os/exec`, `net`, `net/*`, `database/sql`, `log`, `syscall`,
  `unsafe`, `io/ioutil`, `cloud.google.com/*`, `github.com/rs/zerolog`.
- Client I/O: `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`,
  `localStorage`, `sessionStorage`, `indexedDB`, `document.cookie`,
  `navigator.sendBeacon`, `console`.
- Direct clock/random/timer access: `Date.now`, argument-free `new Date()`,
  `Math.random`, `setTimeout`, `setInterval`, `time.Now`, `time.After`,
  `math/rand`, `crypto/rand`.
- Test mocks: `vi.mock`, `vi.spyOn`, `vi.stubGlobal`, fake timers, fetch/MSW
  mocks, `httptest`, sqlmock or fake clients. `vi.fn` must not replace a module
  or global; passing it as an explicit callback input is fine.
- Mutable package/module state: reassignment or mutation of package values,
  `sync.Once*` lazy initialization, Go `init()` side effects, client module-level
  `let`/`var`, or mutation of module-level containers (even declared `const`).
- react-redux access outside `store.ts`, including `useSelector`, `useStore`,
  `connect` and `ReactReduxContext`; action type literals without `<name>/`.

Package values initialized once at declaration and never reassigned or mutated
are allowed: sentinel errors, compiled regexps and read-only lookup tables.
The check script catches `init()` and module-level `let`/`var`; never-mutated
values are an agent rule.

Every export must be testable through its public API using real inputs only.
Callers inject I/O, time, randomness and timer behavior as arguments, callback
props or passed-in functions. Plain in-test functions/values supplied at that
boundary are inputs, not mocks. Rendering, DOM events and component-instance
state (`useState`, `useReducer`) are fine, as is library-owned Redux state.
The mutable-state ban applies to state shared at package/module scope, not
state owned by a component instance or an injected Redux store. A dependency
that requires mocking belongs in reviewed code.

Non-dark client code also imports libraries only through
`src/client/dark/<name>/index`, never deep implementation paths.

## Redux and React integration

A Redux-backed library exports `KEY` (documented default mount key), its `State`
and `Action` types, reducer, `<name>/`-prefixed action creators, slice-only
selectors, components and hooks. The app mounts the reducer at any key and
passes `getState: (root: unknown) => State` once through the library's Provider
or a prop, following the Kepler locator pattern.

Only `store.ts` touches react-redux. Its selector wrapper reads the injected
locator from context, then uses `useSelector(root => select(getState(root)))`.
Throw a clear error when the locator is missing. Never assume root-state keys
or read app slices such as `report`, `dataset` or `workspace`.

Reviewed JS glue mounts `[lib.KEY]: lib.reducer` (or another key), renders
`<lib.Provider getState={s => s[lib.KEY]}>`, maps app/proto data into props, and
passes I/O callbacks such as `onSave` or `fetchRows`. Reviewed actions/thunks
dispatch library actions when server data arrives. Another dark library's state
is accessed only through its exported hook/selector, never its internals.

## Standalone package documentation

The library and its generated README know nothing about Dekart. Do not reference
project concepts, workflows, state shapes, configuration or paths, even to claim
independence from them. Allowed vocabulary comes from library-owned contracts,
third-party dependencies and other dark libraries' public APIs.

Lead with the concrete capability or transformation. Document input/output shapes,
units, invariants, errors and injected behavior. Define each library-owned term by
its contract: an opaque binding ID is a lookup key, not an assumed app dataset;
a pair of owner ID and field is a record, not an assumed app chart or panel.
Name relevant dependencies without explaining what those products are.

Generate the linked TOC and API-at-a-glance table from documentation headings and
public API metadata; never hand-maintain symbol lists in package comments. Keep
README examples short and focused on public usage. Write them inline in doc
comments only when they help; otherwise omit them. Never import test cases,
assertions, test fixtures or harness code into the README. Do not use
`{@includeCode ...}` to pull source code into generated documentation.

From dekart-xyz/dekart, AGPL-3.0.

More from dekart-xyz/dekart