polystella-contributor

name	polystella-contributor
description	Edit the PolyStella package source. Use when adding a file-format adapter, adding a CLI subcommand, adding a translation provider, modifying the cache contract, debugging a translation regression, or otherwise working on the package itself (not consuming it).

polystella-contributor

You are editing the PolyStella package source. This skill is recipes for the common contributor tasks.

If you are integrating PolyStella into a downstream Astro project, STOP and load polystella-consumer instead.

Read first:

• AGENTS.md — orientation, invariants, boundaries.
• ARCHITECTURE.md — subsystem reference.

Then come back here for step-by-step task recipes.

---

Recipes

• Add a file-format adapter
• Add a CLI subcommand
• Add a translation provider
• Change the cache contract
• Debug a translation regression
• Modify a runtime API
• Edit UI-string handling
• Strict tsconfig patterns
• Testing conventions

---

Add a file-format adapter

When to use: Supporting a new file extension (.xml, .html, .po, custom format).

Contract: FileTypeAdapter in src/parsing/adapter.ts. See #adapter-contract.

Steps:

1. Implement the adapter at src/parsing/adapters/<name>.ts:

   import type { FileTypeAdapter, AdapterExtractOptions, AdapterApplyOptions } from "../adapter.js";
   import type { Segment } from "../extract.js";
   
   export const myFormatAdapter: FileTypeAdapter<MyParsedShape> = {
     extensions: [".myext"],
   
     parse(source, sourcePath) {
       // Pure. No I/O. Throw on syntactic errors — the per-pair
       // try/catch in runTranslationPass will surface them without
       // aborting the build.
     },
   
     extractSegments(parsed, source, opts): Segment[] {
       // Emit { id, text } per translatable unit.
       // IDs must be unique within a single file.
       // Empty text → no segment (translating "" is meaningless).
     },
   
     applyTranslations(parsed, source, translations, opts): string {
       // Splice translations back into source bytes.
       // INVARIANT 3: produce the EXACT bytes that will be PUT to R2.
       // Weave any AI-translation marker from opts.topLevelAdditions
       // into the output here, not after.
     },
   
     selectedValuesForHash(parsed, source, opts): Record<string, unknown> {
       // Snapshot of values that feed the cache hash. Only fields
       
     },
   
     (parsed):  {
       
       
     },
   
     
     (bytes, opts):  { ... },   
     (parsed, segments): [][] { ... },  
     (parsed, opts):  |  { ... },
   };
   

---

Add a CLI subcommand

When to use: Adding a new top-level verb (polystella <verb>).

Pattern: Each subcommand owns its argv parsing and a run<Name>(args, deps) handler. The dispatcher in src/cli.ts is a thin router.

Steps:

1. Create src/cli/<name>.ts:

   export interface MySubcommandArgs {
     // Parsed flags.
     help: boolean;
     someFlag?: string;
   }
   
   export const MY_SUBCOMMAND_USAGE = `polystella my-subcommand
   
   <description>
   
   Usage:
     polystella my-subcommand [flags]
   
   Flags:
     --some-flag <value>   ...
     --help                Print this message.
   
   Exit codes:
     0   ok
     1   config error
     2   <subcommand-specific failure>
   `;
   
   export function parseMySubcommandArgs(argv: ReadonlyArray<string>): MySubcommandArgs {
     // Throw on unknown flag or missing value — accept-then-reject
     // would silently swallow typos.
   }
   
   export interface MySubcommandDeps {
     cwd: string;
     log: (msg: string) => void;
     err: (msg: string) => void;
     // Add fakeable I/O / clock / etc. for tests.
   }
   
   export async function runMySubcommand(args: MySubcommandArgs, : ): <> {
     
   }
   

---

Add a translation provider

When to use: Adding a third translator (e.g. OpenAI, Bedrock).

Contract: Translator in src/translation/provider.ts. See #translator-contract.

Steps:

1. Add a config variant to the provider zod schema in src/config/options.ts:

   const newProviderSchema = z.object({
     kind: z.literal("new-provider"),
     apiKey: z.string(),
     model: modelSpecSchema, // string | per-locale map
     maxTokens: z.number().int().positive().default(8192),
     endpoint: z.string().url().optional(),
   });
   
   // Add to the discriminated union:
   const providerSchema = z.discriminatedUnion("kind", [workersAISchema, anthropicSchema, newProviderSchema]);
   

2. Implement the translator factory in src/translation/provider.ts:

   function createNewProviderTranslator(
     provider: NewProviderConfig,
     locale: string,
     fetchImpl: typeof fetch,
   ): Translator {
     const modelId = resolveModelId(provider.model, locale);
   
     return {
       modelId,
       async translate(systemPrompt, userPrompt, signal) {
         const res = await fetchImpl(endpoint, {
           : ,
           : { ... },
           : .({ ... }),
           ...(signal !==  ? { signal } : {}),
         });
   
          (!res.) {
            text =  res.().( );
            message = ;
            (.(res.)) {
               (message);
           }
             (message);
         }
   
          data =  res.();
         
         
          text;
       },
     };
   }
   

---

Change the cache contract

When to use: Modifying any input to the cache hash formula.

Severity: Cache-wide invalidation. Every cached translation across every consumer becomes a miss on the next build.

Steps:

1. Read #cache-key. The current formula is:

   hash = sha256(body + selectedFrontmatterValues + glossaryHash + modelId + optionalExtractionPolicyHash)
   

2. Stop. Coordinate with the owner before merging. This is Invariant 1 in AGENTS.md. The change needs to be in a major version bump and called out in CHANGELOG.

3. If you're confident this is the right change:

   • Edit src/storage/hash.ts (the computeSourceHash function).
   • Update the formula description in ARCHITECTURE.md#cache-key.
   • Update AGENTS.md Invariant #1.
   • Update the hash test pin in tests/storage/hash.test.ts — it pins a literal hash to catch accidental formula drift. Compute the new literal and replace it.
   • Add a CHANGELOG entry under a "Breaking changes" heading.
   • Bump the major version (or 0.x minor pre-1.0).

4. Verify:

   pnpm test
   pnpm exec tsc --noEmit
   

   The pinned-hash test will catch drift if you missed the test update.

---

Debug a translation regression

When to use: A translation that used to work is wrong, missing, or failing.

Diagnostic flow:

1. Reproduce on the fixture. If the regression is reported against a consumer's content, reduce to the smallest source file that reproduces. Add it under tests/fixtures/ if it's worth a regression test.

2. Inspect what the cache layer planned:

   polystella translate --dry-run --file 'path/to/source.md'
   # or in a consumer repo:
   pnpm translate --dry-run --file 'path/to/source.md'
   

   Output includes the planned R2 key. If the key is wrong, the bug is in computeSourceHash or buildR2Key.

3. Inspect the staged output:

   cat <root>/.astro/i18n-staging/<locale>/<source-path>
   

   Compare to expected. Is the AI-translation marker (aiTranslated: true) present? Are URLs rewritten? Is the body translated at all?

4. Inspect the build report:

   cat dist/i18n-r2-report.json | jq '.entries[] | select(.sourcePath == "<path>")'
   

   Outcome will be hit, miss, override, error, or localSkipped. Read the corresponding code path in src/storage/cache.ts or src/source/overrides.ts.

5. Crank up verbosity:

   LOG_LEVEL=debug polystella translate --file 'path/to/source.md'
   

   Emits per-batch detail (segment count, batch count, oversize warnings, retry attempts).

6. Bypass the cache: delete the relevant R2 object, or delete the local index entry:

   rm <root>/.astro/i18n-staging/.polystella-cache.json
   

7. Bypass R2 entirely by passing r2Override: null to runTranslationPass (test-only). Useful for isolating the translator from the cache layer.

8. Common regression causes:

---

Modify a runtime API

When to use: Editing Astro.locals.t, lhref, getLocalizedEntry, getLocalizedCollection, the React hooks, or the middleware that binds them.

Files:

• src/runtime/middleware.ts — request middleware; pre-binds locale to all four locals.
• src/runtime/middleware-core.ts — middleware body (test-friendly extract).
• src/runtime/get-localized-entry.ts, get-localized-collection.ts — fetcher implementations.
• src/runtime/localized-href.ts — URL prefixer.
• src/runtime/custom-loader-runtime.ts — the bridge (module-scoped singleton shared with sibling collections).
• src/runtime/locals.ts — TypeScript ambient declarations for Astro.locals. Was locals.d.ts until the dist-emit rework; renamed so tsc emits both an empty .js and the .d.ts declarations, and runtime/index.ts pulls it in via a side-effect import (the previous triple-slash <reference path> directive gets stripped by tsc at emit time).
• src/react/index.ts — useTranslations, useLocalizedHref hooks.

Key contracts:

• Bridge timing (Invariant 5) — the bridge must be set in astro:config:setup before sibling collections register. Edits that defer bridge setup will silently break sibling content loading.
• Per-locale closures — t, lhref, getLocalizedEntry, getLocalizedCollection are pre-bound to the request's locale by the middleware. Don't expose unbound versions in .astro files — they're imported separately from @cloudflare/polystella/runtime for non-template contexts.

Steps:

1. Edit the relevant runtime file.
2. Update src/runtime/locals.ts if you're changing the shape of Astro.locals.
3. Update the polystella-consumer skill's "Runtime APIs" section.
4. Add tests under tests/runtime/:
   • Behaviour test for the new/changed function.
   • Middleware-binding test if the locals shape changes (tests/runtime/middleware.test.ts).
5. Don't forget the React side — useTranslations / useLocalizedHref and their consumer-side wiring (getDictionary).

---

Edit UI-string handling

When to use: Changing drift detection rules, sync writer behaviour, AI-fill orchestration, or the {{token}} validator.

Files:

• src/i18n/drift.ts — checkI18nDrift, loadAndCheckDrift.
• src/i18n/sync.ts — key reconciliation; layout-aware JSON writer (formatLocaleFile).
• src/i18n/ui-translate.ts — AI-fill orchestrator; {{token}} validator + retry wrapper.
• src/i18n/loader.ts, i18n/index.ts — content-layer loader, dictionary fetcher.
• src/catalog/* — catalog-only public exports, middleware, and Astro integration. Must stay free of content translation, R2, route shims, and localized collection imports.
• src/cli/check-ui.ts, sync-ui.ts, translate-ui.ts — CLI handlers.

Key contracts:

• Three drift failure modes — missing keys, extra keys, empty-placeholder values (a non-default locale has "" where the source has a non-empty string). The build's astro:config:setup drift check and the check-ui CLI use the SAME predicate. If you add a fourth failure mode, update both.
• Layout-aware sync writer — parses the source file's text (not just its JSON) to recover key order and blank-line section breaks. The output mirrors that layout for every locale. Don't drop this — every sync would churn diffs.
• {{token}} validator runs OUTSIDE translateBatch — the orchestrator's retry wrapper sets maxRetries: 0 on translateBatch. Don't add a second retry layer.
• Queued locales catch errors internally — translate-ui pre-scans locale JSONs, skips complete catalogs before provider setup, then runs queued locales in parallel via runWithConcurrency with a hard cap of 3. Each locale is split into small sequential request batches. Workers MUST catch every error and record it on the per-locale outcome — never re-throw. Re-throwing kills the whole run.
• Catalog-only middleware scope — polystella/catalog/middleware binds Astro.locals.t and Astro.locals.lhref only. Do not add localized collection APIs to that surface.

See #ui-strings.

---

Strict tsconfig patterns

All four stricter TypeScript flags are on (noUncheckedIndexedAccess, exactOptionalPropertyTypes, noImplicitReturns, noFallthroughCasesInSwitch). Patterns that come up repeatedly:

noUncheckedIndexedAccess

Indexed access returns T | undefined. Patterns:

// ❌ Old:
const first = arr[0];
first.foo; // type error: first might be undefined

// ✅ Guard:
const first = arr[0];
if (first === undefined) continue;
first.foo;

// ✅ Destructure with default (when default is safe):
const [first = defaultValue] = arr;

exactOptionalPropertyTypes

foo?: string is NOT the same as foo: string | undefined. Callers passing undefined explicitly need the latter:

// ❌ Old:
interface Opts {
  signal?: AbortSignal;
}
function foo(opts: { signal?: AbortSignal }) {
  inner({ signal: opts.signal }); // type error: opts.signal might be `undefined` literal
}

// ✅ When the callee accepts explicit `undefined`:
interface Opts {
  signal?: AbortSignal | undefined;
}

noImplicitReturns

Every code path returns. Add explicit return to early-exit branches:

function foo(): number {
  if (cond) {
    sideEffect();
    return 0;
  } // explicit return
  return 1;
}

Replacing ! and any

! and any are banned outside test code. Replace with:

// ❌
const value = map.get(key)!;
const data = JSON.parse(x) as any;

// ✅
const value = map.get(key);
if (value === undefined) throw new Error(`unexpected: ${key} not in map`);

const data = JSON.parse(x) as unknown;
if (typeof data !== "object" || data === null) throw new Error(`unexpected: ${x}`);
// narrow via structural type guards from here.

---

Testing conventions

• Tests live under tests/<src-dir>/<basename>.test.ts. Top-level exceptions: tests/cli.test.ts (top-level dispatch + translate-subcommand parsing), tests/cli/ (per-subcommand handlers), tests/smoke.test.ts (end-to-end integration smoke).
• Vitest config in vitest.config.ts. singleThread: true — faster than multi-worker at this scale.
• Fakeable boundaries: each subsystem accepts a deps-shaped object so tests can inject stubs. The CLI's runCheckUi(args, deps) shape is the canonical example.
• For tests that need a clean adapter registry: call resetRegistry() before re-registering.
• For tests that exercise R2: use the in-memory R2 client at tests/helpers/in-memory-r2.ts (or whatever the equivalent helper is).
• For tests that exercise the translator: pass translatorOverrides to runTranslationPass with a fake Translator.
• For smoke tests: drive polystella(options) with stubbed Astro context against a real temp project. tests/smoke.test.ts is the template.
• For the doc-claims test (tests/docs.test.ts): pins file paths and command names referenced in AGENTS.md / ARCHITECTURE.md. If you move a file or rename a subcommand, update both the docs AND this test.

Verify before pushing:

pnpm test
pnpm exec tsc --noEmit