@ersbeth/codelife 0.0.0-stage → 0.11.1

package/scripts/target/target-base.md

@@ -0,0 +1,127 @@
+# The base — what every repository has
+
+Whatever its kind. A library or an application adds a toolchain on top of this; a repository whose
+`kind` is `none` stops here, and that is a complete answer, not a degraded one.
+
+## Branches
+
+Gitflow, simplified. `main` is the default branch and is always shippable. `develop` is where
+work lands. **Every work branch carries its issue number** — if the work deserves a branch it
+deserves to be traceable, and when no issue exists yet, one is filed first, even for work already
+done.
+`feature/<issue>-<slug>` and `fix/<issue>-<slug>` are cut from `develop`;
+`hotfix/<issue>-<slug>` from `main` or from a support branch; `lot/<umbrella>-<slug>` carries one
+lot; `support/<major>.<peer>` carries an older peer line. Merge commits everywhere — no squash, no
+fast-forward-only.
+
+## Tracker
+
+The fixed labels — `bug`, `feature`, `severity-critical`, `severity-high`, `severity-mid`,
+`severity-low`, `wontfix`, `lot` — the plugin's three issue templates at the forge's
+native location, and the machine connected to the host `origin` names, one credential per host.
+
+## Scripts
+
+Five, in `package.json`, with these exact names:
+
+| Script | Runs |
+|---|---|
+| `verify:commit` | the fast tier: what must hold before every commit |
+| `verify:push` | the complete tier: what must hold before a push; `/audit`'s baseline |
+| `verify:release` | what must hold before a tag |
+| `test:all` | the whole suite |
+| `test:one` | one test file, passed as the argument |
+
+A repository with no `package.json` at all gets a **private** one carrying the five scripts and an
+`engines` floor — the runtime the port runs on, the Binaries table's rule absent an older
+measurement — and a `package.json` that declares no `engines` gains one the same way, so the
+floor that table defers to is one the port writes. A script with nothing to run prints
+`nothing to run` and exits 0 — which is not the same as a **missing**
+script: that is a *not ported* state, and the port writes it.
+
+## Hooks
+
+Three, versioned in `.githooks/`, wired by `core.hooksPath` from the package's `scripts/install.mjs`, which the repository's
+`prepare` runs and which also sets `fetch.prune`, the clone's other imposed local key, so that a
+clone's view of the forge does not drift as branches are deleted at merge.
+`codelife setup item hooks` writes the line; everywhere else, including here, names the keys.
+Each hook is a stub that hands over to the package's script of the same name and refuses, naming
+the install, when the package is absent:
+
+| Hook | Runs | Why it exists |
+|---|---|---|
+| `pre-commit` | the specification's form, and no tier: `codelife verify commit` is the commit tier's one run | a commit by hand that breaks the specification is refused |
+| `pre-push` | `verify:push`, or `verify:release` when what is pushed is a version tag | a red tip never reaches the remote |
+| `commit-msg` | the Conventional Commits check, a plugin-provided shell script with no dependency | the changelog is generated from these messages |
+
+They are **git** hooks, versioned and readable, not Claude Code hooks: they block a human and an
+agent alike, whatever tool issues the git command. The plugin's own `hooks/` directory stays
+empty by decision — nothing in codelife runs on its own.
+
+## Folders
+
+| Path | Created by |
+|---|---|
+| `docs/audit/README.md` | the port — the campaign table, one row per campaign linking its report at the commit that closed it |
+| `docs/audit/lenses/` | the port |
+| `docs/brainstorm/` | the port — the dated notes `/brainstorm` leaves, pending until the specification absorbs them |
+| `docs/spec/README.md` | the port — the specification's vision and its one index |
+| `docs/spec/users.md`, `docs/spec/glossary.md`, `docs/spec/principles.md` | the port |
+| `docs/spec/journeys/`, `docs/spec/product/`, `docs/spec/system/` | the port — a journey, and a capability under its domain, `product/<activity>/` or `system/<component>/`, is written from its template when a note first creates it |
+
+## Changelog
+
+`CHANGELOG.md` at the root, generated by git-cliff from the commits with the plugin's
+`cliff.toml`. Nothing above the generated/history marker is
+written by hand — `scripts/changelog.mjs` is where that line is spelled, and
+the only place it is: **anything the generator does not produce lives below it**. That covers a
+repository arriving with a hand-written changelog, whose history stays below untouched, and equally
+a repository with no history at all whose changelog carries explanatory prose — the marker is what
+tells a regenerator where to stop, so a file that needs neither still gains nothing by omitting it.
+
+## Binaries
+
+What the plugin needs from the machine, by name. *script*: a `verify:*` tier calls it, so a miss
+turns a gate red. *skill*: a skill calls it, so a miss stops that skill and nothing else.
+The plugin's own repository derives a prerequisites suite from this table and runs it before
+every other suite, so a missing binary is named before the suite that would have met it first
+reports a wrong cause. The **floor** is the lowest version the plugin's use is known to work on —
+absent an older measurement, the version it was measured on — with its reason beside it; the same
+suite compares each binary's `--version` against it. A floor is lowered only by re-measuring every
+use that cites it. A cell reads `<version> — <reason>`, `none` — with or without a reason the
+same way — or `engines`, and its first token is what is compared; a row naming several binaries
+writes `` `name` <floor> `` per name,
+`;`-separated. `none` is presence only. `engines` defers to `package.json`, the one place a
+runtime floor lives.
+
+| Binary | Class | Floor | Needed by |
+|---|---|---|---|
+| `git` | script | 2.23 — `switch`, which `/work` and `codelife release cut` run to put a run on its branch | every hook and every skill |
+| `sh` | script | none — the clone's own `/bin/sh`, bash on macOS and dash on Debian, and no version compares across them: a parse check measures whichever is here, so the templates are held to both (measured under bash 3.2 and dash) | every hook the port writes runs under it |
+| `node` | script | engines | the package manager runs on it, and every script, `spec-form.mjs` included, which a hook runs as `node <path>` on the installed package's file; each refuses to run below the floor and says so, through `scripts/node-floor.mjs` |
+| `pnpm`, `npm` or `yarn` — the one the lockfile names | script | engines | the hooks run `verify:*` through it |
+| `claude` | skill | 2.1.312 — a subagent dispatched with no model running on its dispatcher's, which keeps a campaign's lenses on their judge's Opus, measured there and on no older version | the plugin runs inside it |
+| `glab` or `gh` — the one `tracker.kind` names | skill | `glab` 1.113.0 — every form the scripts under `scripts/tracker/` send was read and measured at it, and `label create --name` needs it; `gh` none — the thread reads were measured at 2.101.0, and a floor waits for a whole review measured on it | every `codelife` verb that reads or writes the tracker; `none` needs neither |
+| `npx` | skill | none — it ships with `node`, whose floor is `engines`; measured at 10.9.3 | the `reproduce` agent's browser, through the server the plugin declares. The browser itself is the server's: at the pinned version its default channel is the machine's Google Chrome, which `npx playwright install chrome` fetches and nothing downloads on first use — an `.app` is not on `PATH`, so no row here can see it, and a miss surfaces as the server's own error, `Chromium distribution 'chrome' is not found` |
+
+## Marker
+
+Every file the plugin writes opens with a `generated by codelife` marker, and the tail after it says
+**who owns the file** — so a contributor who opens one reads its status from the file itself, rather
+than looking it up in a list somebody has to maintain. Two owners — the plugin, or this
+repository — spelled four ways between them, and no third owner:
+
+| Tail | Meaning |
+|---|---|
+| `edit the plugin, not this file` | the plugin owns this copy; change it in the plugin and re-port |
+| `edit the plugin's template, not this file` | the same, where the marker is a shell comment rather than an HTML one |
+| `/<skill>` | this repository grows the file, and that skill is what writes it |
+| `maintained by hand` | this repository grows the file, and no skill writes it |
+
+A **template** carries the marker its *deployment* should carry, never one about itself: the reader
+of the deployed file is who the marker is for.
+
+A tail that names nobody — the bare `<!-- generated by codelife -->` — is the one thing this
+vocabulary forbids, because it forces the reader back to a list. The plugin's own marker suite
+derives its wordings and its by-hand tail from this table, and the skill names from the skills
+themselves.

package/scripts/target/target-lib.md

@@ -0,0 +1,143 @@
+# A conforming library — on top of the base
+
+Everything in `target-base.md` applies here in full; this file adds the toolchain, and nothing it
+says replaces a base row.
+
+A library is a package other repositories consume. That is the only thing distinguishing it from
+an application here, and it decides every row below: the build is a `pack` rather than a bundle,
+the output is versioned so a consumer can install from the forge, and the dev mode never imports
+that output.
+
+## Package manager
+
+pnpm, pinned in `packageManager`, with `minimumReleaseAge` set explicitly in `pnpm-workspace.yaml` —
+`1440`, pnpm's own 24 hours, unless the repository already sets a value. Only an explicit value makes
+pnpm refuse a release younger than the window; left at its default, pnpm writes an exclusion for it
+and installs. A library with in-house dependencies is a workspace:
+`pnpm-workspace.yaml` with `packages: [submodules/*]`, each in-house library a **root** submodule
+initialised non-recursively, and `pnpm.overrides` sending every in-house package to `workspace:*`.
+Submodules are the end state, not a transition, so a `file:`
+specification is converted, never kept beside one.
+
+`shamefully-hoist` is never applied to make a phantom dependency work: the phantom is declared, or
+it is filed as a debt.
+
+## Toolchain
+
+Vite+, invoked as `vp`: the `vite-plus` devDependency, installed with the repository's other
+dependencies and run through its scripts — not a machine binary. One `vite.config.ts` at the root,
+`defineConfig(mergeConfig(library({ entry }), { … }))`: the package's preset carries the `pack`
+block and has Vite read `tsconfig.json`'s `paths`, which map the package name to `src/` for the
+tests and any playground — one mapping the type checker and Vite share, one file, not one per mode. What a repository adds, a plugin or a test setting, goes in
+the object `mergeConfig` takes; that merge concatenates arrays, so what varies from one library to
+the next is a parameter of `library`, and a value the preset fixes is the target's, not one to
+replace.
+
+The target commits to the **configuration surface** and the `vp` scripts, not to Vite+ itself,
+which is beta: if it stalls, the same configuration runs under Vite, Vitest, Oxlint and Oxfmt
+installed separately, which changes this file and not the target.
+
+## Build
+
+`vp pack`. ESM only — no CommonJS output and no dual package. Every dependency external, both
+`dependencies` and `peerDependencies`, so a consumer resolves one copy of each. `dts: true`, so the
+types ship with the build rather than being written by hand — emitted through the `typescript`
+devDependency, without which `vp pack` refuses to build them.
+
+The output is `dist/`, and `dist/` is **versioned**. A consumer installs
+the library from the forge by tag, with no build step of its own, which is what a `prepare` script
+building at install time cannot promise across package managers.
+
+## Types
+
+`tsconfig.json` extending the package's `presets/tsconfig.json`, which fixes `strict`,
+`verbatimModuleSyntax`, `moduleResolution: bundler` and `noEmit` — the repository keeps `target`,
+`lib` and `include`. The emit belongs to `vp pack`, which is why the type checker does none. Checked by `vp check`, which type-checks only because the preset sets both
+`lint.options.typeAware` and `lint.options.typeCheck`.
+
+`target` and `lib` are the exception: they name the ECMAScript edition the library's runtime floor
+supports — the floor its `engines` declares, and any browser it documents — so they differ from one
+library to the next. The template's `ES2022` is where a library needing nothing newer starts; one
+calling a later standard API raises both to its floor, which states what it needs and relaxes
+nothing. Pinned to an edition either way, never `ESNext`, which moves every consumer's floor with
+the next TypeScript release.
+
+An error is fixed, never silenced by a blanket `any`; a `// @ts-expect-error` carries the reason it
+is there, and an error worth keeping is worth an issue.
+
+## Lint and format
+
+Oxlint and Oxfmt, both through `vp check`. No Biome, no ESLint, no Prettier — one formatter, so a
+file's shape does not depend on which tool last touched it.
+
+The linter is not swapped the way the formatter is: its value is the rules someone enabled after
+being bitten, so the old one's are carried over rule by rule. Oxlint runs **type-aware** —
+`lint.options.typeAware` in the vite preset — because without it every rule that needs the type
+checker, `typescript/no-floating-promises` among them, is silent even set to `error`, and
+`vp check` still reports no lint error.
+
+## Tests
+
+Vitest through `vp test`. `test/` mirrors `src/`, so the test for a module is where its path says
+it is and nothing has to be searched for.
+
+Configured in `vite.config.ts`'s `test` block, like everything else. A suite whose environment
+differs — a browser, a runtime flag, no mapping to the source — is an inline project in
+`test.projects`, run alone with `vp test --project <name>`, and inherits the root's `resolve` and
+plugins only through `extends: true`. Coverage is the root's: a suite's thresholds are keyed there
+by the sources it covers, because a project's own `coverage` is ignored without a word.
+
+The characterisation tests written when the repository was ported — the public surface, the import
+of the current build, the examples turned into tests — are kept as the **floor**: they describe the
+behaviour consumers already depend on, so they are extended, never weakened to let a change pass.
+
+## Dev mode
+
+A `playground/` is **optional**: a library has one when it wants a page, and none otherwise — both
+conform. A library whose behaviour a test shows better than a
+page gains nothing from one but a file the type check keeps alive.
+
+When there is one, it conforms on two points. It imports the library **by its package name**, which
+`tsconfig.json`'s `paths` map to `src/` — never from `dist/`, never through a relative path
+into `src/`: a playground reading the build shows the last
+`pack`, not the working tree, which is the one thing a dev mode must not do. And the manifest carries
+a `dev` script, `PLAYGROUND=1 vp dev`, which the configuration's `root` line reads to serve
+`playground/`. The server starts from the package root, not with `vp dev playground`: Vite looks its
+configuration up in the root it is given, so serving the folder loads no `vite.config.ts` and the
+package name resolves to nothing. It is not a workspace package depending on the library.
+
+## Hooks
+
+The base's three, and the stubs are the base's. The `pre-commit` script, reading `kind: lib` in the
+contract, runs each `generated[]` entry whose `when` is not empty and stages its path with the
+commit: `dist/` is versioned, so a commit touching `src/` without it leaves the build behind its
+source in the same history — and a consumer installing that tag gets the old code from a repository
+whose source says otherwise. A library still on its former bundler declares that bundler's command,
+and nothing is built where nothing is declared.
+
+The contract of a conforming library declares its output so:
+`generated: [{ path: dist/, command: pnpm exec vp pack, when: [src/**] }]` — in a workspace, the
+ported package's `dist/` and `pnpm --dir <package> exec vp pack`. Item `d` of the port writes it, in
+the commit that replaces the build, since the command it names changes at that instant. The build
+runs unconditionally, not behind a "did src/ change" test, since the build is the authority on
+whether its output moved; stages with `-A` so that a file the build stopped producing is staged as
+the deletion it is; and packs from the working tree, so when the index and the tree differ the
+commit can carry output its own source does not.
+
+## Standard scripts
+
+The base's five names, with a library's commands, verbatim:
+
+| Script | Runs |
+|---|---|
+| `verify:commit` | `vp check && vp test` |
+| `verify:push` | `vp check && vp test && vp pack` |
+| `verify:release` | `pnpm verify:push` |
+| `test:all` | `vp test` |
+| `test:one` | `vp test` |
+
+`test:one` takes the file as its argument. `pack` is in the push tier and not the commit tier: the
+commit tier runs on every commit and a full build there costs more than it catches, while a push is
+what makes `dist/` someone else's problem. `verify:release` is the push tier itself: the `pre-push`
+hook and `/release` run it alone on a version tag, so it holds everything the push tier holds; the
+tag naming the version is `/release`'s to check, and the publication job's.

package/scripts/target/templates/audit/README.md

@@ -0,0 +1,21 @@
+<!-- generated by codelife — /audit -->
+# Audits
+
+One row per campaign in the table below, linking its report — an index and one file per lens —
+**at the commit that closed it**. The folder
+itself, `A<n>-<date>-full/` or `A<n>-<date>-targeted-<LENS>-<LENS>/`, lives here only while the
+campaign runs: the close commits it complete, then a second commit deletes it and writes its row,
+so the tree carries no findings true at a commit long gone. `/audit` reads the next campaign number
+from this table. What has to change about a finding changes in its issue, which carries the finding
+whole.
+
+## Campaigns
+
+| Campaign | Date | Type | Commit | Findings | State |
+|---|---|---|---|---|---|
+
+`lenses/<id>.md` holds the domain lenses this repository adds to the plugin's, one file per lens.
+Written from the plugin's template at the first campaign that needs one.
+
+A full campaign is due every six months, and before a major; a targeted one before a minor.
+`/overview` says when the last one was.

package/scripts/target/templates/characterisation/bundle.test.ts

@@ -0,0 +1,43 @@
+// generated by codelife — maintained by hand
+//
+// The bundle's shape. A size that jumps is almost always a dependency that stopped being external
+// and got bundled in — the one regression no behavioural test notices and every consumer pays for.
+// Measured over all the JavaScript beside the entry points, shared chunks included, since that is
+// where a newly bundled dependency usually lands.
+//
+// The tolerance is wide enough not to fire on noise and narrow enough to catch that. Widen it with
+// a reason in the commit message, never to make a red run go away.
+import { describe, expect, it } from 'vitest'
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { entries } from './entries'
+
+const TOLERANCE = 0.1 // ±10%
+const BASELINE = resolve(__dirname, 'bundle.baseline.json')
+
+const javascript = (dir: string): string[] =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) return javascript(path)
+    return /\.m?js$/.test(entry.name) ? [path] : []
+  })
+
+const files = [...new Set(Object.values(entries()).map(dirname).flatMap(javascript))]
+const bytes = files.reduce((total, file) => total + statSync(file).size, 0)
+
+describe('the bundle', () => {
+  it('keeps its module format', () => {
+    // Recorded, not asserted: the build before the port may be CommonJS, and item `d`'s move to ES
+    // modules is then this snapshot's one deliberate update.
+    const format = (code: string) => (/\bmodule\.exports\b|\brequire\(/.test(code) ? 'commonjs' : 'es module')
+    expect([...new Set(files.map((file) => format(readFileSync(file, 'utf8'))))].sort()).toMatchSnapshot()
+  })
+
+  it('stays within the tolerance of its baseline size', () => {
+    // Recorded by the first run, the way a snapshot is, before the toolchain is replaced — and
+    // committed with the snapshots. Deleting it re-records it: do that only with a reason.
+    if (!existsSync(BASELINE)) writeFileSync(BASELINE, `${JSON.stringify({ bytes }, null, 2)}\n`)
+    const baseline = JSON.parse(readFileSync(BASELINE, 'utf8')).bytes
+    expect(Math.abs(bytes - baseline) / baseline).toBeLessThan(TOLERANCE)
+  })
+})

package/scripts/target/templates/characterisation/declarations.test.ts

@@ -0,0 +1,44 @@
+// generated by codelife — maintained by hand
+//
+// The declarations are what a consumer's compiler breaks on, and no other test reads them: the unit
+// tests and the surface snapshot run JavaScript. Each entry point's declaration file is type-checked
+// the way a consumer's project meets it — its own `lib`, and `skipLibCheck` off.
+//
+// A new bundler is where this goes red. Declaration *bundling* rewrites the entry modules into
+// chunks, and a directive at the top of an entry — `/// <reference lib="esnext.disposable"
+// preserve="true" />` — does not survive it: the build succeeds and the declarations no longer
+// compile. Under `vp pack`, `pack.outputOptions.banner` puts the directive back on the entry chunks
+// ending in `.d.ts`; `pack.dts.banner` is accepted and silently ignored.
+import { describe, expect, it } from 'vitest'
+import ts from 'typescript'
+import { entries } from './entries'
+
+// The edition of the library's runtime floor, as the target's `## Types` states it, set when this
+// file is written: a consumer is not assumed to compile with more. Never raise it to make a red run
+// go away — that is the consumer's build failing instead.
+const EDITION = 'ES2022'
+
+const declarations = entries('types')
+
+describe('the shipped declarations', () => {
+  it('are declared for every entry point', () => {
+    expect(Object.keys(declarations).sort()).toEqual(Object.keys(entries()).sort())
+  })
+
+  it('type-check as a consumer compiles them', () => {
+    const program = ts.createProgram(Object.values(declarations), {
+      noEmit: true,
+      strict: true,
+      skipLibCheck: false,
+      lib: [`lib.${EDITION.toLowerCase()}.d.ts`, 'lib.dom.d.ts'],
+      target: ts.ScriptTarget[EDITION],
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+    })
+    const diagnostics = ts.getPreEmitDiagnostics(program).map((d) => {
+      const where = d.file ? `${d.file.fileName}: ` : ''
+      return `${where}TS${d.code} ${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`
+    })
+    expect(diagnostics).toEqual([])
+  })
+})

package/scripts/target/templates/characterisation/entries.ts

@@ -0,0 +1,50 @@
+// generated by codelife — maintained by hand
+//
+// The entry points the package declares, read from its manifest: what a consumer can import, and so
+// what every characterisation test walks. Read once here, so the tests cannot disagree about what
+// the package ships — and a subpath added to `exports` is characterised without editing a test.
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+type Target = string | null | Target[] | { [condition: string]: Target }
+
+// What each kind of entry resolves through, and what a file of that kind looks like. A condition
+// object is read in that order, an array through its first target that resolves; `require` alone is
+// not an entry an ES consumer loads.
+const kinds = {
+  code: { conditions: ['import', 'default'], file: /\.m?js$/ },
+  types: { conditions: ['types', 'import', 'default'], file: /\.d\.m?ts$/ },
+}
+
+function pick(target: Target, kind: (typeof kinds)[keyof typeof kinds]): string | undefined {
+  if (typeof target === 'string') return kind.file.test(target) ? target : undefined
+  if (Array.isArray(target)) return target.map((t) => pick(t, kind)).find(Boolean)
+  if (target === null) return undefined
+  for (const condition of kind.conditions) {
+    const file = condition in target ? pick(target[condition], kind) : undefined
+    if (file) return file
+  }
+  return undefined
+}
+
+/** Each declared subpath, and the absolute path of the JavaScript file — or with `'types'`, the
+ *  declaration file — it resolves to. */
+export function entries(kind: keyof typeof kinds = 'code'): Record<string, string> {
+  const root = resolve(__dirname, '../..')
+  const manifest = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'))
+  const declared = manifest.exports ?? manifest.main
+  // `exports` is either a map of subpaths, all starting with `.`, or the target of `.` itself.
+  const subpaths: Record<string, Target> =
+    declared && typeof declared === 'object' && !Array.isArray(declared) &&
+    Object.keys(declared).some((key) => key.startsWith('.'))
+      ? declared
+      : { '.': declared ?? null }
+  const found: Record<string, string> = {}
+  for (const [subpath, target] of Object.entries(subpaths)) {
+    // The manifest's top-level `types` answers for `.` when `exports` names no declaration.
+    const file = pick(target, kinds[kind]) ?? (kind === 'types' && subpath === '.' ? manifest.types : undefined)
+    // A pattern (`./*`) names no one file, and `./package.json` is not code.
+    if (file && !subpath.includes('*')) found[subpath] = resolve(root, file)
+  }
+  return found
+}

package/scripts/target/templates/characterisation/examples.test.ts

@@ -0,0 +1,18 @@
+// generated by codelife — maintained by hand
+//
+// The usage the author thought worth showing, turned into tests. For most repositories this is the
+// closest thing to a specification that exists, and until now it was prose nothing ran.
+//
+// One test per example, named after where it came from, so a failure says which piece of
+// documentation is now wrong.
+import { describe, expect, it } from 'vitest'
+
+describe('the documented examples', () => {
+  it.todo('README.md — the opening example')
+  // Copy each example here verbatim first and watch it pass. Only then tidy it: an example edited
+  // on the way in is no longer evidence of what the documentation claims.
+
+  it('has at least one example under test', () => {
+    expect(true).toBe(true) // replace with the first real example, then delete this line
+  })
+})

package/scripts/target/templates/characterisation/import.test.ts

@@ -0,0 +1,22 @@
+// generated by codelife — maintained by hand
+//
+// A build that produces a file nothing can import fails no other test: the unit tests run against
+// the source, and the surface snapshot reads the module without exercising it. This one loads the
+// shipped artefact the way a consumer does and uses it once.
+import { describe, expect, it } from 'vitest'
+import { entries } from './entries'
+
+describe('the shipped build', () => {
+  for (const [subpath, file] of Object.entries(entries())) {
+    it(`imports ${subpath}`, async () => {
+      const built = await import(file)
+      expect(Object.keys(built).length).toBeGreaterThan(0)
+    })
+  }
+
+  it('runs its main entry point once', async () => {
+    // Replace with the smallest real call the library offers — the one its README opens on.
+    const built = await import(entries()['.'])
+    expect(built).toBeDefined()
+  })
+})

package/scripts/target/templates/characterisation/surface.test.ts

@@ -0,0 +1,68 @@
+// generated by codelife — maintained by hand
+//
+// What a consumer breaks on. Written BEFORE the toolchain is replaced and run against the build as
+// it stood then, so that a missing export after the port is a failure rather than a discovery.
+//
+// It reads the built package, not the source: the source can export something the build drops.
+// Every entry point `exports` declares is read, each under its own subpath, so a build that drops
+// an export from a secondary entry fails as surely as one that drops it from the root.
+//
+// The module object holds only what exists at runtime, so the declaration file is read too: an
+// interface or a type alias has no binding, and its removal would change no other snapshot. Its
+// names are held, not its text — types are rewritten on purpose by the port, and reformatted by
+// declaration bundling, without a consumer's import breaking. A build that ships no declaration file
+// gets the lines between the `declarations` markers left out, and the item says so.
+// <declarations>
+import ts from 'typescript'
+// </declarations>
+import { describe, expect, it } from 'vitest'
+import { entries } from './entries'
+
+const built = await Promise.all(
+  Object.entries(entries()).map(async ([subpath, file]) => [subpath, await import(file)] as const),
+)
+
+it('finds at least one entry point in the manifest', () => {
+  expect(built.length).toBeGreaterThan(0)
+})
+
+// <declarations>
+const declarations = entries('types')
+const program = ts.createProgram(Object.values(declarations), { noEmit: true, skipLibCheck: true })
+const checker = program.getTypeChecker()
+
+function declaredNames(file: string): string[] {
+  const symbol = checker.getSymbolAtLocation(program.getSourceFile(file)!)
+  return symbol ? checker.getExportsOfModule(symbol).map((s) => s.getName()).sort() : []
+}
+// </declarations>
+
+for (const [subpath, module] of built) {
+  describe(`the public surface of ${subpath}`, () => {
+    it('exports the same names', () => {
+      expect(Object.keys(module).sort()).toMatchSnapshot()
+    })
+
+    it('exports the same kinds', () => {
+      const kinds = Object.fromEntries(
+        Object.entries(module).map(([name, value]) => [name, typeof value]),
+      )
+      expect(kinds).toMatchSnapshot()
+    })
+
+    it('keeps each function’s arity', () => {
+      const arities = Object.fromEntries(
+        Object.entries(module)
+          .filter(([, value]) => typeof value === 'function')
+          .map(([name, value]) => [name, (value as (...a: unknown[]) => unknown).length]),
+      )
+      expect(arities).toMatchSnapshot()
+    })
+
+    // <declarations>
+    it('declares the same names', () => {
+      expect(declaredNames(declarations[subpath])).toMatchSnapshot()
+    })
+    // </declarations>
+  })
+}

package/scripts/target/templates/cliff.toml

@@ -0,0 +1,61 @@
+# generated by codelife — edit the plugin's template, not this file
+#
+# git-cliff renders CHANGELOG.md from the commit messages. Only what a reader of
+# this repository can observe gets an entry: features, fixes, performance. The
+# rest — documentation, tooling, CI, refactors, tests, chores — shaped the work
+# and is read in the git history, not in the changelog.
+
+[changelog]
+header = """
+# Changelog
+
+All notable changes to this project are documented here. The entries are generated
+from the commit messages by git-cliff; the sections below the marker, when there is
+one, are the hand-written history that preceded it.
+
+"""
+body = """
+{% if version %}\
+{#- the version alone, under either tag spelling: `v0.1.0`, or the CLI's `<name>--v0.1.0` -#}
+## [{{ version | split(pat="--v") | last | trim_start_matches(pat="v") }}] — {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+## [Unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | upper_first }}
+{% for commit in commits %}\
+- {% if commit.scope %}**{{ commit.scope }}**: {% endif %}\
+{{ commit.message | upper_first }}\
+{% if commit.breaking %} — **breaking**{% endif %}
+{% endfor %}\
+{% endfor %}\n
+"""
+footer = ""
+trim = true
+
+[git]
+conventional_commits = true
+# false, not true: with `true`, a commit that is not a Conventional Commit — every merge commit —
+# is discarded *before* commit_parsers and its rejection is printed as a parse error, so the
+# warning count grows by one per merge, forever, and can never signal anything. With `false` it
+# reaches the parsers, where the catch-all `{ message = "^.*", skip = true }` below already drops
+# it. Measured: identical output either way, and no warning.
+filter_unconventional = false
+filter_commits = true
+tag_pattern = "(^|--)v[0-9]"
+sort_commits = "oldest"
+
+# The subject decides, and the Conventional Commits footer, never the prose. A parser that reads
+# the body — `{ body = ".*security" }` was the tempting one — puts a design note that merely
+# *discusses* security into the changelog, which is exactly the rule these entries exist to keep:
+# what a reader of this repository can observe, nothing else. A security fix is a `fix`, and lands
+# in Fixed. A break is observable whatever its type, so a breaking commit — `!` in the subject or a
+# `BREAKING CHANGE:` footer, the two the bump counts — that no type above takes lands in Changed: a
+# `refactor!` that retires a skill is news to whoever installs the package.
+commit_parsers = [
+  { message = "^feat[(!:]", group = "Added" },
+  { message = "^fix[(!:]", group = "Fixed" },
+  { message = "^perf[(!:]", group = "Performance" },
+  { field = "breaking", pattern = "true", group = "Changed" },
+  { message = "^.*", skip = true },
+]

package/scripts/target/templates/githooks/commit-msg

@@ -0,0 +1,9 @@
+#!/bin/sh
+# generated by codelife — edit the plugin's template, not this file
+#
+# Refuses a commit message that is not a Conventional Commit.
+# It hands over to the package, and refuses when the package is not installed: git would run
+# nothing else, and a guard that vanishes without a word is none.
+
+[ -f node_modules/@ersbeth/codelife/scripts/commit-msg.mjs ] || { echo "codelife is not installed here: run your package manager's install (node_modules/@ersbeth/codelife is missing), then retry." >&2; exit 1; }
+exec node node_modules/@ersbeth/codelife/scripts/commit-msg.mjs "$@"

package/scripts/target/templates/githooks/pre-commit

@@ -0,0 +1,9 @@
+#!/bin/sh
+# generated by codelife — edit the plugin's template, not this file
+#
+# Holds the specification's form, and a library's dist/, before a commit.
+# It hands over to the package, and refuses when the package is not installed: git would run
+# nothing else, and a guard that vanishes without a word is none.
+
+[ -f node_modules/@ersbeth/codelife/scripts/pre-commit.mjs ] || { echo "codelife is not installed here: run your package manager's install (node_modules/@ersbeth/codelife is missing), then retry." >&2; exit 1; }
+exec node node_modules/@ersbeth/codelife/scripts/pre-commit.mjs "$@"

package/scripts/target/templates/githooks/pre-push

@@ -0,0 +1,9 @@
+#!/bin/sh
+# generated by codelife — edit the plugin's template, not this file
+#
+# Runs the verification tier before a push, so that a red tip never reaches the remote.
+# It hands over to the package, and refuses when the package is not installed: git would run
+# nothing else, and a guard that vanishes without a word is none.
+
+[ -f node_modules/@ersbeth/codelife/scripts/pre-push.mjs ] || { echo "codelife is not installed here: run your package manager's install (node_modules/@ersbeth/codelife is missing), then retry." >&2; exit 1; }
+exec node node_modules/@ersbeth/codelife/scripts/pre-push.mjs "$@"

package/scripts/target/templates/playground/index.html

@@ -0,0 +1,11 @@
+<!-- generated by codelife — maintained by hand -->
+<!doctype html>
+<meta charset="utf-8" />
+<title><package-name> playground</title>
+<h1><package-name></h1>
+<p>
+  This page imports the library from <code>src/</code> through the <code>paths</code> of
+  <code>tsconfig.json</code>, never from <code>dist/</code> — so what you see is the working tree.
+</p>
+<pre id="out"></pre>
+<script type="module" src="./main.ts"></script>