@theodo/bernard 0.1.0-beta.0 → 0.1.0-beta.1

package/dist/docs/assets/CONTRIBUTING.md.DwJsKrz3.js

@@ -0,0 +1,33 @@
+import{_ as s,o as a,c as t,a3 as n}from"./chunks/framework.hgjl6W6o.js";const k=JSON.parse('{"title":"Contributing","description":"","frontmatter":{},"headers":[],"relativePath":"CONTRIBUTING.md","filePath":"CONTRIBUTING.md"}'),o={name:"CONTRIBUTING.md"};function i(r,e,c,p,d,h){return a(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="contributing" tabindex="-1">Contributing <a class="header-anchor" href="#contributing" aria-label="Permalink to &quot;Contributing&quot;">​</a></h1><p>This guide is for changing the factory itself. To set it up in a project, start from <a href="./docs/getting-started.html">docs/getting-started.md</a>.</p><h2 id="set-up" tabindex="-1">Set up <a class="header-anchor" href="#set-up" aria-label="Permalink to &quot;Set up&quot;">​</a></h2><p>Node 24, pnpm and <code>jq</code>, then <code>pnpm install</code>. The tests and the worktree hook need <code>jq</code>. To try your clone&#39;s CLI on a project, run <code>pnpm bernard &lt;command&gt; --cwd &lt;project&gt;</code>. To try it as a project gets it, <code>pnpm pack</code>, then <code>pnpm --dir .factory --ignore-workspace add -E &lt;tarball&gt;</code> from the project&#39;s root.</p><h2 id="checks" tabindex="-1">Checks <a class="header-anchor" href="#checks" aria-label="Permalink to &quot;Checks&quot;">​</a></h2><p>CI runs them on every pull request (<a href="https://github.com/theodo-group/bernard/blob/v0.1.0-beta.1/.github/workflows/ci.yml" target="_blank" rel="noreferrer">ci.yml</a>):</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> lint</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                  # Biome; pnpm format fixes it</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> typecheck</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> check:consumers</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">       # knip: code lands only when production source uses it (ADR-0013)</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> check:knip-baseline</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # the exceptions in knip.json only shrink</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> check:sync</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">            # what bernard sync generates, here and in fixtures/, is up to date</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> check:docs</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">            # docs/pipeline.md matches the state machines, and the documentation site builds with no dead link</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> check:package</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">         # the package installs and runs in a project outside this repo</span></span></code></pre></div><p>When <code>check:sync</code> fails, run <code>pnpm sync:all</code>; when <code>check:docs</code> fails on the pipeline, <code>pnpm docs:pipeline</code>. Commit what they write. When it fails on a link, fix the link: <a href="./packages/docs/README.html">packages/docs/README.md</a> says how the site reads them.</p><p>The demo runs the factory end to end, on a local Coder or on the local runner: <a href="./demo/README.html">demo/README.md</a>.</p><h2 id="run-the-factory-on-this-repo" tabindex="-1">Run the factory on this repo <a class="header-anchor" href="#run-the-factory-on-this-repo" aria-label="Permalink to &quot;Run the factory on this repo&quot;">​</a></h2><p><code>bernard run</code> runs each ticket in a workspace of a local Coder, cloned from <code>main</code> on GitHub: a ticket&#39;s changes to the factory reach the workspaces once merged. The runner sets <code>local: true</code>, so the run starts that Coder in Docker, signs the Coder CLI in to it and pushes the reference template as <code>ai-mod-factory</code> (<a href="./docs/recipes.html#a-local-coder">docs/recipes.md</a>).</p><p>This repo&#39;s <code>.factory/</code> runs bernard from its source: <code>pnpm --dir .factory --ignore-workspace install</code> once sets up <code>.factory/node_modules/.bin/bernard</code>.</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> GH_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">gh</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> auth token)&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # the workspaces clone, push and open pull requests with it</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> CLAUDE_CODE_OAUTH_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">…</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">.factory/node_modules/.bin/bernard</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --feature</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">issu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">.factory/node_modules/.bin/bernard</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> view</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # follows it on http://localhost:4321, once \`pnpm build\` built the viewer and the docs</span></span></code></pre></div><p>The sessions get one Claude Code credential: <code>CLAUDE_CODE_OAUTH_TOKEN</code> when it is set, <code>ANTHROPIC_API_KEY</code> otherwise. <code>bernard run</code> tries it with a one-turn session first. One the API rejects, or none at all, starts <code>claude setup-token</code> at a terminal and refuses the run without one. A workspace whose agent is not ready within 5 minutes stops the run, with the <code>coder</code> command that fixes it, and one whose agent missed the Coder&#39;s connection timeout stops it at once.</p><p>To run on your machine without Coder, set <code>adapters.runner</code> in <code>.factory/factory.config.ts</code> to the local runner (ADR-0030): <code>{ type: &#39;local&#39;, worktree: { setup: &#39;pnpm install --frozen-lockfile&#39; } }</code>. The feature and each ticket then run in a git worktree under <code>tmp/factory/worktrees/</code>, from your local <code>main</code>, and your checkout is left as it is.</p><p>To work on the viewer itself, <code>pnpm dev:viewer</code> serves it with Vite on the runs in <code>tmp/factory/runs</code>, or in the folder <code>BERNARD_RUNS</code> names (<a href="./packages/viewer/README.html">packages/viewer/README.md</a>).</p><p>To work on the documentation, <code>pnpm dev:docs</code> serves the site live on <a href="http://localhost:5173/docs/" target="_blank" rel="noreferrer">http://localhost:5173/docs/</a>. Its pages are the markdown of this repo; a new page goes in the sidebar (<a href="./packages/docs/README.html">packages/docs/README.md</a>).</p><h2 id="the-package" tabindex="-1">The package <a class="header-anchor" href="#the-package" aria-label="Permalink to &quot;The package&quot;">​</a></h2><p>The root of this repo is the one package projects install, <code>@theodo/bernard</code> (ADR-0011). <code>pnpm build</code> bundles <code>packages/*</code> into <code>dist/</code> with tsdown (<a href="https://github.com/theodo-group/bernard/blob/v0.1.0-beta.1/tsdown.config.ts" target="_blank" rel="noreferrer">tsdown.config.ts</a>), and builds the viewer&#39;s page into <code>dist/viewer/</code> with Vite: its React packages are the viewer&#39;s <code>devDependencies</code>, inputs of that build, never installed by a project. It then builds the documentation site into <code>dist/docs/</code> with VitePress, a <code>devDependency</code> of <code>packages/docs</code> likewise (ADR-0037). The package ships all three; <code>files</code> in <code>package.json</code> adds <code>core/</code> and the starter overlays. The CLI finds them, and the module a project&#39;s config imports, through <a href="https://github.com/theodo-group/bernard/blob/v0.1.0-beta.1/packages/cli/src/package.ts" target="_blank" rel="noreferrer">packages/cli/src/package.ts</a>, from its source as from <code>dist/</code>.</p><p>A config field goes in the schema of <a href="https://github.com/theodo-group/bernard/blob/v0.1.0-beta.1/packages/contracts/src/config.ts" target="_blank" rel="noreferrer">packages/contracts/src/config.ts</a>, or of <code>pipeline.ts</code>, and in <code>FactoryConfigInput</code>, the documented type a project writes against: a type test fails while they differ (ADR-0024). Its row goes in the tables of <a href="./docs/overlay.html">docs/overlay.md</a>.</p><p>A third-party package the CLI imports goes in three places: the catalog of <code>pnpm-workspace.yaml</code>, which the workspace packages use, the root&#39;s <code>dependencies</code>, which a project installs, and <code>neverBundle</code> in <code>tsdown.config.ts</code>. The build fails on a package it would bundle instead.</p><p>An adapter, code tied to one outside tool, goes in <code>&lt;package&gt;/src/adapters/&lt;tool&gt;/</code>, one folder per tool. Code outside <code>adapters/</code> never imports one, and an adapter never imports another. Only <a href="https://github.com/theodo-group/bernard/blob/v0.1.0-beta.1/packages/cli/src/bin.ts" target="_blank" rel="noreferrer">bin.ts</a> wires them, through <code>createRunner</code>, <code>createTracker</code> and <code>createForge</code>, so a new adapter is a folder plus one branch there. Biome refuses such an import (ADR-0038). A file holds one concept, named by the file: its type, its schema and the functions that act on it. Utils files are exempt, and a file that needs a section comment to separate two ideas is two files.</p><p>A file imports relatively only inside the top-level folder of <code>src/</code> or <code>test/</code> it sits in. The rest of its package it reaches through the package&#39;s subpath import, <code>#&lt;package&gt;/</code>, which the <code>imports</code> of its <code>package.json</code> maps to <code>src/</code>: <code>#cli/runners/runner.ts</code>, never <code>../../runners/runner.ts</code>. Another package it imports by its name, declared in <code>package.json</code>. Biome refuses a relative import that climbs to the package root, with one pattern per folder depth: <code>../**</code> for the files of <code>src/</code>, <code>src/&lt;folder&gt;/</code> and <code>test/</code>, <code>../../**</code> for <code>src/adapters/&lt;tool&gt;/</code>. A folder nested deeper needs its own override in <a href="https://github.com/theodo-group/bernard/blob/v0.1.0-beta.1/biome.json" target="_blank" rel="noreferrer">biome.json</a>.</p><h2 id="release" tabindex="-1">Release <a class="header-anchor" href="#release" aria-label="Permalink to &quot;Release&quot;">​</a></h2><p>A version is published on npm, and a GitHub release of this repo holds its notes (ADR-0035).</p><ol><li>On a branch, run <code>pnpm release</code> and pick the next version. It writes it to <code>package.json</code> and runs <code>pnpm sync:all</code>, so the lock files record it.</li><li>Commit, open a pull request, and merge it.</li></ol><p>That is all: don&#39;t create a tag, and don&#39;t publish by hand. Once merged, the <a href="https://github.com/theodo-group/bernard/blob/v0.1.0-beta.1/.github/workflows/release.yml" target="_blank" rel="noreferrer">Release workflow</a> sees a version with no tag yet (ADR-0040). It checks the package, publishes the tarball <code>pnpm pack</code> writes on npm with npm&#39;s trusted publishing, then creates the GitHub release and the tag <code>vX.Y.Z</code> on the merge commit. A version with a suffix, such as <code>-beta.0</code>, is a pre-release, under the dist-tag <code>next</code>; any other under <code>latest</code>. The workflow then installs the version from npm, as a project does.</p><h2 id="how-a-run-fits-together" tabindex="-1">How a run fits together <a class="header-anchor" href="#how-a-run-fits-together" aria-label="Permalink to &quot;How a run fits together&quot;">​</a></h2><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>┌─ the machine that runs bernard ──────────────────────────────────────┐</span></span>
+<span class="line"><span>│  CLI  packages/cli        the run&#39;s trace, to the telemetry port:    │</span></span>
+<span class="line"><span>│        │                  for humans and bernard view, never replayed│</span></span>
+<span class="line"><span>│        ▼                                                             │</span></span>
+<span class="line"><span>│  orchestrator  packages/orchestrator, no I/O: the machines, the      │</span></span>
+<span class="line"><span>│                record&#39;s lines, and their replay on resume            │</span></span>
+<span class="line"><span>│        │ StepRunner port                     │ AppendRecord port     │</span></span>
+<span class="line"><span>│        ▼                                     ▼                       │</span></span>
+<span class="line"><span>│  runner adapters  packages/cli/src/adapters/: coder/, local/, over   │</span></span>
+<span class="line"><span>│                  the git scripts of runners/git.ts                   │</span></span>
+<span class="line"><span>└────────┬─────────────────────────────────────────────────────────────┘</span></span>
+<span class="line"><span>         │ bash, or coder ssh</span></span>
+<span class="line"><span>┌─ a working copy per ticket, and one for the feature ─────────────────┐</span></span>
+<span class="line"><span>│  local: a git worktree · coder: a workspace                          │</span></span>
+<span class="line"><span>│  a step     a fresh harness session: writes code within its write    │</span></span>
+<span class="line"><span>│             scope, and its handoff in .pipeline/&lt;ticket&gt;/&lt;step&gt;-&lt;n&gt;/ │</span></span>
+<span class="line"><span>│  the runner appends to .pipeline/&lt;ticket&gt;/log.jsonl, and commits it  │</span></span>
+<span class="line"><span>└────────┬─────────────────────────────────────────────────────────────┘</span></span>
+<span class="line"><span>         │ git push, if the branch has an upstream · git fetch, on resume</span></span>
+<span class="line"><span>┌─ the project&#39;s remote ───────────────────────────────────────────────┐</span></span>
+<span class="line"><span>│  each record on its branch: the feature&#39;s on feat/&lt;feature&gt;-&lt;slug&gt;,  │</span></span>
+<span class="line"><span>│  a ticket&#39;s on ticket/&lt;feature&gt;-&lt;ticket&gt;                             │</span></span>
+<span class="line"><span>└──────────────────────────────────────────────────────────────────────┘</span></span></code></pre></div><p>The decisions behind it: ports (ADR-0004), write scopes (ADR-0014), records (ADR-0017, ADR-0020). <code>bernard sync</code>, the other half, renders <code>core/</code> and a project&#39;s overlay into its harness&#39;s files (ADR-0003).</p><h2 id="how-a-change-lands" tabindex="-1">How a change lands <a class="header-anchor" href="#how-a-change-lands" aria-label="Permalink to &quot;How a change lands&quot;">​</a></h2><ul><li><strong>A ticket</strong> on the project board: <a href="./docs/github.html">docs/github.md</a>.</li><li><strong>The vocabulary</strong> of <a href="./CONTEXT.html">CONTEXT.md</a>.</li><li><strong>An ADR</strong> in <a href="https://github.com/theodo-group/bernard/tree/v0.1.0-beta.1/docs/adr" target="_blank" rel="noreferrer">docs/adr/</a>, written with the <code>/adr</code> skill.</li><li><strong>The guides</strong> in <code>docs/</code> and the starters in <a href="https://github.com/theodo-group/bernard/tree/v0.1.0-beta.1/fixtures/starters" target="_blank" rel="noreferrer">fixtures/starters/</a> follow every change a project sees.</li><li><strong>The rules</strong> of <a href="./CLAUDE.html">CLAUDE.md</a>, for humans too.</li><li><strong>Core content</strong> in English, following <a href="./core/README.html">core/README.md</a>, and no secrets in the core or an overlay.</li><li><strong>Commits</strong> in Conventional Commits, merged after peer review with CI green.</li><li><strong>Under the PolyForm Shield License 1.0.0</strong>, like the rest of the repo (<a href="https://github.com/theodo-group/bernard/blob/v0.1.0-beta.1/LICENSE" target="_blank" rel="noreferrer">LICENSE</a>): no CLA to sign, and you keep the copyright on your change (ADR-0033).</li></ul>`,32)])])}const g=s(o,[["render",i]]);export{k as __pageData,g as default};

package/dist/docs/assets/CONTRIBUTING.md.DwJsKrz3.lean.js

@@ -0,0 +1 @@
+import{_ as s,o as a,c as t,a3 as n}from"./chunks/framework.hgjl6W6o.js";const k=JSON.parse('{"title":"Contributing","description":"","frontmatter":{},"headers":[],"relativePath":"CONTRIBUTING.md","filePath":"CONTRIBUTING.md"}'),o={name:"CONTRIBUTING.md"};function i(r,e,c,p,d,h){return a(),t("div",null,[...e[0]||(e[0]=[n("",32)])])}const g=s(o,[["render",i]]);export{k as __pageData,g as default};