@ape-egg/codecane 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# @ape-egg/codecane
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build a project up step by step. Each step folder holds only what that step adds, plus patches that store just the lines it changes in earlier files. codecane stacks steps 1 through n into a complete, runnable folder for step n, checks that every step still runs, and shows the steps as a timeline with their stories and diffs.
+
+codecane works only on folders, so it doesn't care which version control you use, or whether you use any.
+
+```sh
+bun add -d @ape-egg/codecane
+bunx codecane check    # replays every step and runs its checks, or stops at the first that breaks
+bunx codecane merge <step> <other…>  # tries merging timelines, writing nothing
+bunx codecane dev      # viewer at http://localhost:3000, or $PORT; rebases later patches as steps change
+bunx codecane build    # dist/: stacked steps, data and viewer, every step checked
+bunx codecane stack <step>/<hash>… --out dir  # one step on one timeline, ready to deploy
+bunx codecane agents   # the workflow section for your AGENTS.md
+```
+
+## A project
+
+```
+steps/
+  1/                 what step 1 adds
+    index.html
+    main.js
+  1.html             its story: <h1>Name</h1> and a few paragraphs
+  2/
+    score.js
+    index.html.patch only the lines step 2 changes in step 1's index.html
+  2.html
+  hard-mode/         a pivot: another way on from step 1
+    hard.js
+    index.html.patch
+    codecane.json       { "parent": "1" }
+  hard-mode.html
+```
+
+A patch is unified-diff hunks, applied exactly at their line numbers:
+
+```diff
+@@ -7,4 +7,5 @@
+   <link rel="stylesheet" href="style.css">
+   <script type="module" src="main.js"></script>
++  <script type="module" src="score.js"></script>
+ </head>
+ <body>
+```
+
+To write one, copy the earlier file into the step, edit it, and run `codecane patch <step> <path>`. The copy turns into a patch that holds only the changed lines.
+
+`codecane.json` holds the step's short hash, and knows four more keys:
+
+| key | meaning |
+| --- | --- |
+| `hash` | The step's short hash, generated once by codecane when it first sees the step. |
+| `parent` | The step this one continues. It defaults to the step before it in natural order, and `null` starts a new root. Any step can be a parent, as long as parents never lead back to the step itself. Steps that share a parent are a pivot, and the one whose id sorts first leads the default timeline. A list of steps continues all of their timelines together. See [Continuing timelines together](#continuing-timelines-together). |
+| `merges` | Steps on other timelines that this step merges into its own. See [Merging timelines](#merging-timelines). |
+| `removes` | Earlier files this step takes away. |
+| `overrides` | Earlier files this step replaces with a full copy. A copy that isn't listed fails the build. Prefer a patch. |
+
+Steps can be numbered (`1`, `2`, `10`) or named (`canvas`, `moving-the-center`). Named steps say their `parent`.
+
+Stacking is a pure function of the step folders. It walks from the root to the step, and each step drops its `removes`, lays its files on top, and applies its patches exactly where they say. There is no merging, fuzz or guessing, and nothing is generated.
+
+`steps/<id>.check.js` is a step's optional check. Its default export gets the stacked step's files as `{ path: text }` and throws when the step doesn't do what it should. A step without a check still stacks and builds, and is marked untested.
+
+## Continuing timelines together
+
+A pivot's timelines can be alternatives, such as a square and a hex floor for the same game. To write the next steps once for all of them, give a step several parents: `{ "parent": ["hex", "square"] }`. It continues each of those timelines on its own. Nothing is combined: the step and every step after it stack once per timeline, onto that timeline's own files, so each timeline keeps what it chose.
+
+- The first parent leads the default timeline.
+- Every step can be visited at `/<step>`, which shows it with the default fork at each fork on the way. Once forks have been chosen, the default one included, its address is `/<step>/<hash>/<hash>…`: the short hashes of the step taken at each fork before it, earliest first, such as `/moving-the-center/05adc6a`. Only forks before the step count, so a step before any fork, or the step a fork takes, never carries one. `codecane stack moving-the-center/05adc6a --out dir` writes that timeline's step alone, ready to deploy.
+- A step's patches have to apply on every timeline it continues, and its checks run on every one. `codecane check` names the timeline where one doesn't.
+- When the timelines differ where the later steps need them, they get a seam: a small internal API that each timeline fills in. The step that owns that code on each timeline fills it in. A step with several parents that holds code of its own is a **seam** (yellow), like a merge step that holds code. It is always needed, because its code is what the timelines share from there on.
+
+## Merging timelines
+
+Any number of timelines can merge at any step. A merge is one step that names the other timelines' steps in `merges`. It replays their stored code onto its own timeline exactly, and never merges text. codecane decides what kind of step it is by replaying and running every check on both sides:
+
+- **Merge**: the step holds no code, everything replays cleanly and every check passes.
+- **Seam** (yellow): the timelines differ, so the step holds a small internal API that each of them fills in, and the viewer shows which steps required it and why.
+- **Seam no longer needed**: replaying without the seam still passes every check, here and in every later step. The timeline leaves it out, and `codecane check` says so.
+
+Every step has a short hash, generated once when codecane first sees the step and stored as `hash` in its `codecane.json`. `codecane check`, `build`, `dev` and the other commands give a new step one. A seam lives in `parts/<hash>/`, beside `steps/`, with its story at `parts/<hash>.html`: its short hash is its id and its folder name, and later steps name it by that hash. Its story has no `<h1>`; the viewer titles it `Seam <hash>`. `codecane check` gives a seam written in `steps/` its hash and fails with where in `parts/` to move it, and fails on a step in `parts/` that holds no seam. Sangido's is `parts/612a36a/`.
+
+Adding steps later never changes a merge's kind. Editing a step from before it replays the merge again. `codecane merge` tries a merge without writing anything. The viewer shows merges but never makes them. Agents follow the steps in [workflow.md](workflow.md).
+
+## Patches always apply
+
+The stored steps must stack cleanly at all times. Conflicts are dealt with when an edit is made, never at build time:
+
+- **Saving in the viewer** writes the file to the step that last changed it. Every later patch is then rebased onto the new text: each change block (the lines a patch removes, and the gap where it inserts) moves to its new line, and the patch's context is rewritten. If an edit touches lines a later patch removes, or inserts at the exact spot where a later patch inserts, the save is refused with the step and lines, and nothing is written.
+- **`codecane dev` watches `steps/`**, whichever tool writes there. Once the writes settle, it turns copies of earlier files into patches, rebases later patches the same way, and logs every patch it can't rebase. Then it replays from the changed step forward, quietly when everything passes, or stops at the first step that breaks and says why. The open viewer then updates in place: the story, the timeline and the diff follow the new steps, a changed stylesheet is swapped into the running step, and any other changed file restarts the running step.
+- **`codecane check`** replays every step and runs its checks. It fails with the step, the file and the lines of each patch that no longer applies, or stops at the first failing check. Run it after every edit to a step folder.
+
+## The check
+
+`codecane build` writes every stacked step and links each one with `Bun.build`, the way a browser would load it. Absolute paths resolve against the site, bare imports need an import map, and every `src` and `href` in the step's pages must exist. A call to a function an earlier step renamed, a missing file and an unmapped import all fail the build. The check runs on Bun.
+
+## The data
+
+The build writes `codecane/index.json`, which is the contract any viewer reads:
+
+```json
+{
+  "codecane": 1,
+  "name": "tally",
+  "editable": false,
+  "steps": [{ "id": "2", "hash": "6e61352", "parents": ["1"], "merges": [], "title": "Counter", "children": ["3", "history"], "joins": [], "kind": null, "untested": true, "data": { "2": "2.b81cfa88f74a.json" } }],
+  "timelines": [["1", "2", "3", "4"], ["1", "2", "history", "history-clear"]],
+  "stacks": [["1", "2", "3", "4/6e61352"], ["1", "2", "history", "history-clear/8252275"]]
+}
+```
+
+Each step's file is named by a hash of its content, so it can be cached forever:
+
+```json
+{
+  "id": "2",
+  "address": "2",
+  "parents": ["1"],
+  "title": "Counter",
+  "story": "<h1>Counter</h1>…",
+  "convergence": null,
+  "untested": true,
+  "folder": "../steps/2/",
+  "files": [{ "path": "index.html", "owner": "1", "patchedBy": ["2"], "changedBy": "2", "hash": "…", "overrides": null }],
+  "dependencies": [],
+  "changes": [{ "path": "features/hello.js", "state": "removed", "before": "…", "after": "", "added": 0, "removed": 4, "lines": [["-", "import …"]] }]
+}
+```
+
+`hash` is the step's short hash. `data` names a file for every address of a step, one per timeline it is on, and `stacks` gives each timeline's addresses, `<step>/<hash>…`, in the same order as `timelines`. A seam that is no longer needed is left out of both. `joins` lists the merge steps that continue a step's timeline, and `kind` is a merge step's kind, `merge`, `seam` or `obsolete`, and `seam` on a step with several parents that holds code. A merge step's `convergence`, and a seam's on a step with several parents, holds its `kind`, its `merges`, the parents it `continues` together, the steps it `brought`, the steps a seam is `requiredBy`, and the `reasons`. `owner` is the step that brought a file, `patchedBy` lists the steps that patched it since, and `changedBy` is the last of them, which is where a fix goes. `dependencies` lists the stacked `package.json`'s dependencies. `changes` is the diff against the parent's stacked step on the same timeline: every added, modified and removed file, with both texts and the line diff (`' '` kept, `'-'` removed, `'+'` added).
+
+## The site
+
+```
+dist/
+  index.html, <address>/index.html   the viewer, at / and /<address>
+  codecane/index.json, codecane/<address>.<hash>.json
+  codecane/ui/                     the viewer's files
+  steps/<address>/              every step on every timeline, runnable on its own
+  node_modules/                 the viewer's and the steps' dependencies
+```
+
+Any static host serves it as is.
+
+## The viewer
+
+The viewer is built with [Vibe](https://vibe.korte.kim) and reads only the data above. It shows a timeline of the chosen path, a story panel, the step running live, and its diff. When the steps fork, the fork marker in the timeline folds out every path through it, and clicking a step there follows that path. The page's address names the forks chosen before it, and the viewer keeps to the timeline you are on with every click, in the timeline or the story; a step that continues several timelines runs the one of that timeline. With the fork marker unfolded, pressing a fork navigates straight to it when the step you are on comes before it, such as Canvas, or is itself a fork beside it, such as World hex surface beside World triangle surface. From a step after the fork, pressing a step on another fork picks that fork without leaving the step you are on: the address's hashes change to the new fork, such as `/moving-the-center` becoming `/moving-the-center/05adc6a`, and the preview reruns on it. Pressing a step on the picked fork, once it is picked, navigates to that step. A seam shows in the timeline with its number and mirrored fork icon, and no name, and its story panel is titled `Seam <hash>`, above its Seam section and its story. Clicking a file opens it in an editor. The diff redraws as you type, and Run starts the step with your draft. In `codecane dev` the viewer hot-reloads its own files through Vibe's hot module refresh: an edited component is refreshed in place, an edited stylesheet is swapped, and only a change to its scripts reloads the page. You can also save the file to the step that last changed it, and a save that would break a later patch is refused with the step and lines. A patched file shows as modified in the step that patches it, with just those lines in its diff.
+
+A merge step, and a step with several parents that holds code, shows the fork icon mirrored, in yellow for a seam, and its story panel says what it continues or brought and why it is the kind it is. A seam that is no longer needed isn't shown.
+
+Core (`@ape-egg/codecane`: `read`, `stack`, `replay`, `tree`, `revise`, `rebaseLater`, `patchCopies`, `trial`, `convergence`, `replayed`, `entry`, `index`, `changes`, `build`, `check`, `serve`) never imports the viewer. The viewer only reads core's JSON, so either one can be replaced on its own.

package/core/build.js

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs'
+import { cp, mkdir, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import { check } from './check.js'
+import { entry, hash, index } from './data.js'
+import { dependencies, located } from './modules.js'
+import { stack, tree } from './stack.js'
+import { read, stamp } from './steps.js'
+
+const listed = async dir => (await readdir(dir, { recursive: true, withFileTypes: true }))
+  .filter(entry => entry.isFile() && !entry.name.startsWith('.'))
+  .map(entry => join(entry.parentPath, entry.name).slice(dir.length + 1))
+
+export const written = async (out, files) => Promise.all(Object.entries(files).map(async ([path, body]) => {
+  const file = join(out, path)
+  if (existsSync(file) && (await readFile(file)).equals(Buffer.from(body))) return
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, body)
+}))
+
+const viewerFiles = async ({ dir }, ids) => {
+  const paths = await listed(dir)
+  const shell = await readFile(join(dir, 'index.html'))
+  return {
+    ...Object.fromEntries(await Promise.all(paths.map(async path => [`codecane/ui/${path}`, await readFile(join(dir, path))]))),
+    'index.html': shell,
+    ...Object.fromEntries(ids.map(id => [`${id}/index.html`, shell])),
+  }
+}
+
+export const build = async ({ project, out = join(project, 'dist'), viewer }) => {
+  await stamp(project)
+  const steps = await read(project)
+  const { name } = JSON.parse(await readFile(join(project, 'package.json'), 'utf8'))
+  const { located: placed, addresses: stacked } = tree(steps)
+  const stacks = Object.fromEntries(stacked.map(id => [id, stack(steps, placed[id].id, placed[id].through)]))
+  const entries = Object.fromEntries(await Promise.all(stacked.map(async id => [id, JSON.stringify(await entry(steps, id))])))
+  const data = Object.fromEntries(stacked.map(id => [id, `${id}.${hash(entries[id])}.json`]))
+  const modules = new Map([
+    ...(viewer?.modules ?? []).map(module => [module, located(module, viewer.dir)]),
+    ...stacked.flatMap(id => dependencies(stacks[id].files)).map(module => [module, located(module, project)]),
+  ])
+
+  await rm(out, { recursive: true, force: true })
+  await written(out, {
+    'codecane/index.json': JSON.stringify(await index(steps, { name, address: id => data[id] })),
+    ...Object.fromEntries(stacked.map(id => [`codecane/${data[id]}`, entries[id]])),
+    ...Object.fromEntries(stacked.flatMap(id => Object.entries(stacks[id].files).map(([path, body]) => [`steps/${id}/${path}`, body]))),
+    ...viewer && await viewerFiles(viewer, Object.keys(placed)),
+  })
+  await Promise.all([...modules].map(async ([module, dir]) => cp(await realpath(dir), join(out, 'node_modules', module), { recursive: true })))
+
+  const failures = {}
+  for (const id of stacked) {
+    const problems = await check({ site: out, folder: join(out, 'steps', id), files: stacks[id].files })
+    if (problems.length) failures[id] = problems
+  }
+
+  return {
+    out,
+    steps: stacked,
+    overrides: steps.flatMap(({ id }) => stacks[stacked.find(address => placed[address].id === id)].overrides.filter(override => override.step === id)),
+    failures,
+  }
+}

package/core/check.js

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs'
+import { join, posix } from 'node:path'
+
+const external = /^([a-z][a-z0-9+.-]*:|\/\/)/i
+const bare = specifier => !external.test(specifier) && !/^\.{0,2}\//.test(specifier)
+
+const importMaps = html => [...html.matchAll(/<script type="importmap">([\s\S]*?)<\/script>/g)].map(([, map]) => JSON.parse(map).imports ?? {})
+
+const brokenLinks = ({ site, folder, files }) => Object.keys(files).filter(path => path.endsWith('.html')).flatMap(page => [...files[page].toString().matchAll(/\s(?:src|href)="([^"#?]+)/g)]
+  .map(([, link]) => link)
+  .filter(link => !external.test(link))
+  .filter(link => !existsSync(link.startsWith('/') ? join(site, link) : join(folder, posix.dirname(page), link)))
+  .map(link => `${page} links ${link}, which is missing`))
+
+const browser = ({ site, folder, imports }) => ({
+  name: 'browser',
+  setup: build => build.onResolve({ filter: /.*/ }, ({ path, importer }) => {
+    if (!importer) return undefined
+    const mapped = imports[path] ?? path
+    if (external.test(mapped)) return { path: mapped, external: true }
+    if (bare(mapped)) throw new Error(`${importer.slice(folder.length + 1)} imports ${path}, which no import map in the step names`)
+    if (mapped.startsWith('/')) return { path: join(site, mapped) }
+    if (mapped !== path) return { path: join(folder, mapped) }
+    return undefined
+  }),
+})
+
+export const check = async ({ site, folder, files }) => {
+  const imports = Object.assign({}, ...Object.keys(files).filter(path => path.endsWith('.html')).flatMap(page => importMaps(files[page].toString())))
+  const scripts = Object.keys(files).filter(path => path.endsWith('.js')).map(path => join(folder, path))
+  const linked = scripts.length ? await Bun.build({ entrypoints: scripts, target: 'browser', throw: false, plugins: [browser({ site, folder, imports })] }) : { logs: [] }
+  const local = text => text.replace(/[^\s"]*?steps\/[^/\s"]+\//g, '')
+  return [
+    ...brokenLinks({ site, folder, files }),
+    ...linked.logs.filter(log => log.level === 'error').map(log => log.position?.line ? `${local(log.message)} (${local(log.position.file)}:${log.position.line})` : local(log.message)),
+  ]
+}

package/core/checks.js

@@ -0,0 +1,94 @@
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+
+import { describe, graphOf, layered, merged, ownPaths, replay, tree, unkeyed } from './stack.js'
+
+const loaded = async path => (await import(`${path}?${createHash('sha256').update(await readFile(path)).digest('hex').slice(0, 12)}`)).default
+
+const texts = files => Object.fromEntries(Object.entries(files).map(([path, body]) => [path, body.toString()]))
+
+export const checksAt = (steps, id, through = []) => {
+  const step = steps.find(step => step.id === id)
+  return (step.merges.length ? tree(steps).lineage(id, through) : [id]).map(id => steps.find(step => step.id === id)).filter(step => step.check)
+}
+
+export const untested = (steps, id) => !checksAt(steps, id).length
+
+export const converges = step => step.merges.length > 0 || step.parents.length > 1 && ownPaths(step).length > 0
+
+export const failuresOf = async (steps, id, files, through = []) => {
+  const failures = []
+  for (const step of checksAt(steps, id, through)) {
+    try {
+      await (await loaded(step.check))(texts(files))
+    } catch (error) {
+      failures.push({ step: step.id, at: id, message: error.message })
+    }
+  }
+  return failures
+}
+
+const bare = step => ({ ...step, files: {}, patches: {}, removes: [], overrides: [] })
+
+export const trial = async (steps, step, layers = replay(steps)) => {
+  const { ways, brought } = graphOf(steps)
+  const tried = []
+  for (const through of ways(step.id)) {
+    const { clashes } = merged(step, through, layers, steps)
+    tried.push({ clashes, failures: clashes.length ? [] : await failuresOf(steps, step.id, layered(bare(step), through, layers, steps).files, through) })
+  }
+  const [clashes, failures] = [tried.flatMap(line => line.clashes), tried.flatMap(line => line.failures)]
+  return { brought: [...new Set(ways(step.id).flatMap(through => brought(step.id, through)))], clashes, failures, clean: !clashes.length && !failures.length }
+}
+
+const breaksWithout = async (steps, id) => {
+  try {
+    const without = step => ({ ...bare(step), merges: tree(steps).brought(id).length ? step.merges : [] })
+    const { stop } = await replayed(steps.map(step => step.id === id ? without(step) : step), [id])
+    return stop && unkeyed(stop).id
+  } catch {
+    return id
+  }
+}
+
+export const convergence = async (steps, id, layers = replay(steps)) => {
+  const step = steps.find(step => step.id === id)
+  const continues = step.parents.length > 1 ? step.parents : []
+  if (!step.merges.length) return { kind: 'seam', merges: [], continues, brought: [], requiredBy: [], clashes: [], failures: [] }
+  const { brought, clashes, failures, clean } = await trial(steps, step, layers)
+  const seam = ownPaths(step).length > 0
+  const later = seam && clean ? await breaksWithout(steps, id) : null
+  return {
+    kind: seam ? clean && !later ? 'obsolete' : 'seam' : 'merge',
+    merges: step.merges,
+    continues,
+    brought,
+    requiredBy: seam ? [...new Set([...clashes, ...failures].map(problem => problem.step).concat(later ?? []))] : [],
+    clashes,
+    failures,
+  }
+}
+
+export const reasonOf = ({ clashes, failures }) => [
+  ...clashes.map(({ step, path, below }) => `step ${step}'s change to ${path} doesn't replay onto ${path} as step ${below} leaves it`),
+  ...failures.map(({ step, message }) => `step ${step}'s check fails: ${message}`),
+]
+
+export const replayed = async (steps, from = steps.map(step => step.id)) => {
+  const layers = replay(steps)
+  const { lineage, keys } = graphOf(steps)
+  const reached = keys.filter(key => lineage(unkeyed(key).id, unkeyed(key).through).some(id => from.includes(id)))
+  for (const key of reached) {
+    const { id, through } = unkeyed(key)
+    const conflicts = layers[key].conflicts.filter(conflict => conflict.step === id)
+    if (conflicts.length) return { stop: key, why: conflicts.map(describe) }
+    const failures = await failuresOf(steps, id, layers[key].files, through)
+    if (failures.length) return { stop: key, why: failures.map(({ step, message }) => `step ${step}'s check fails${through.length ? ` on the timeline through ${through.join(', ')}` : ''}: ${message}`) }
+  }
+  const affected = steps.filter(step => reached.some(key => unkeyed(key).id === step.id))
+  const obsolete = []
+  for (const step of affected.filter(step => step.merges.length && ownPaths(step).length)) {
+    if ((await convergence(steps, step.id, layers)).kind === 'obsolete') obsolete.push(step.id)
+  }
+  return { stop: null, obsolete, untested: affected.filter(step => untested(steps, step.id)).map(step => step.id) }
+}

package/core/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env bun
+import { watch } from 'node:fs'
+import { readFile, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+
+import { build, written } from './build.js'
+import { reasonOf, replayed, trial } from './checks.js'
+import { patchCopies } from './rebase.js'
+import { serve } from './serve.js'
+import { conflictsOf, describe, locate, named, replay, stack } from './stack.js'
+import { persisted, read, stamp } from './steps.js'
+
+const usage = `codecane check [project]                    replay every step and run its checks, and stop at the first step that breaks
+codecane merge <step> <step...> [--project dir]   try merging timelines into the first step's, without writing anything
+codecane patch <step> [file...] [--project dir]   turn a step's copies of earlier files into patches
+codecane dev [project] [--port n]          serve the viewer and every stacked step, live from steps/, rebasing later patches as steps change
+codecane build [project] [--out dir]       stack every step into dist/, write its data and the viewer, and check that every step runs
+codecane build [project] --bare            the same without the viewer
+codecane stack <address> [project] --out dir  write one step on one timeline, <forks-step>@<fork-step>@<step>
+codecane stack <address> [project] --out dir --watch  the same, and write it again as steps/ changes, touching only the files that changed
+codecane agents                            print the codecane workflow for a project's AGENTS.md`
+
+const root = resolve(import.meta.dirname, '..')
+const { dependencies } = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
+const viewer = { dir: join(root, 'ui'), modules: Object.keys(dependencies) }
+
+const { positionals: [command, ...rest], values } = parseArgs({
+  allowPositionals: true,
+  options: { port: { type: 'string' }, out: { type: 'string' }, bare: { type: 'boolean' }, watch: { type: 'boolean' }, project: { type: 'string' } },
+})
+
+const stamped = async (project = '.') => {
+  await stamp(resolve(project))
+  return read(resolve(project))
+}
+
+const commands = {
+  check: async ([project = '.']) => {
+    const steps = await stamped(project)
+    const conflicts = conflictsOf(replay(steps))
+    conflicts.forEach(conflict => console.error(describe(conflict)))
+    if (conflicts.length) {
+      console.info(`${conflicts.length} ${conflicts.length === 1 ? 'step no longer replays' : 'steps no longer replay'}`)
+      process.exitCode = 1
+      return
+    }
+    const { stop, why, obsolete, untested } = await replayed(steps)
+    if (stop) {
+      console.error(`the replay stops at step ${named(stop)}:\n  ${why.join('\n  ')}`)
+      process.exitCode = 1
+      return
+    }
+    obsolete.forEach(id => console.info(`the seam in step ${id} is no longer needed, so the timeline leaves it out.`))
+    console.info(`all ${steps.length} steps stack cleanly and pass their checks${untested.length ? `; untested: ${untested.join(', ')}` : ''}`)
+    process.exitCode = 0
+  },
+  merge: async ([into, ...tips]) => {
+    const steps = await stamped(values.project)
+    const trying = { id: 'codecane', parents: [into], merges: tips, title: 'Merge', story: '', check: null, removes: [], overrides: [], files: {}, patches: {} }
+    const result = await trial([...steps, trying], trying)
+    const brought = `brings ${result.brought.join(', ')} onto step ${into}`
+    if (result.clean) return console.info(`a clean merge: it ${brought}, and every check passes. To merge, add a step whose codecane.json says { "parent": "${into}", "merges": ${JSON.stringify(tips)} }.`)
+    console.info(`a seam is needed: it ${brought}, and\n  ${reasonOf(result).join('\n  ')}\nTo merge, add a step whose codecane.json says { "parent": "${into}", "merges": ${JSON.stringify(tips)} }, holding the seam that makes these replay. Write it in steps/ with the step that needs it, and codecane check gives it its short hash and says where in parts/ it goes.`)
+  },
+  patch: async ([id, ...paths]) => {
+    const { copies, writes } = patchCopies(await stamped(values.project), id, paths)
+    await persisted(resolve(values.project ?? '.'), writes)
+    console.info(copies.length ? `step ${id} now patches ${copies.join(', ')}` : `step ${id} has no copies of earlier files to turn into patches`)
+  },
+  dev: async ([project = '.']) => serve({ project: resolve(project), viewer, port: Number(values.port ?? process.env.PORT ?? 3000) }),
+  build: async ([project = '.']) => {
+    const { out, steps, overrides, failures } = await build({ project: resolve(project), out: values.out && resolve(values.out), viewer: !values.bare && viewer })
+    overrides.forEach(({ step, path, over }) => console.info(`override: step ${step} brings its own ${path} over step ${over}'s`))
+    Object.entries(failures).forEach(([id, problems]) => console.error(`step ${id} does not run:\n  ${problems.join('\n  ').replaceAll('\n', '\n  ')}`))
+    console.info(`${steps.length - Object.keys(failures).length} of ${steps.length} stacked steps run, written to ${out}`)
+    process.exitCode = Object.keys(failures).length ? 1 : 0
+  },
+  stack: async ([address, project = '.']) => {
+    const out = resolve(values.out)
+    const stackedFiles = async () => {
+      const steps = await stamped(project)
+      const { id, through } = locate(steps, address)
+      return stack(steps, id, through).files
+    }
+    let files = await stackedFiles()
+    await written(out, files)
+    console.info(`step ${address} stacked into ${out}`)
+    if (!values.watch) return
+    const restacked = async () => {
+      const next = await stackedFiles()
+      const changed = Object.keys(next).filter(path => !(path in files) || !Buffer.from(files[path]).equals(Buffer.from(next[path])))
+      const gone = Object.keys(files).filter(path => !(path in next))
+      await written(out, Object.fromEntries(changed.map(path => [path, next[path]])))
+      await Promise.all(gone.map(path => rm(join(out, path))))
+      files = next
+      if (changed.length || gone.length) console.info(`step ${address} stacked into ${out} again: ${[...changed, ...gone].join(', ')}`)
+    }
+    let settling
+    let queue = Promise.resolve()
+    watch(resolve(project), { recursive: true }, (_, path) => {
+      if (!/^(steps|parts)\//.test(path ?? '')) return
+      clearTimeout(settling)
+      settling = setTimeout(() => queue = queue.then(restacked).catch(error => console.error(error.message)), 300)
+    })
+  },
+  agents: async () => console.info(await readFile(join(root, 'workflow.md'), 'utf8')),
+}
+
+if (commands[command]) await commands[command](rest)
+else console.info(usage)

package/core/data.js

@@ -0,0 +1,64 @@
+import { createHash } from 'node:crypto'
+
+import manifest from '../package.json' with { type: 'json' }
+
+import { convergence, converges, reasonOf, untested } from './checks.js'
+import { changes } from './diff.js'
+import { dependencies } from './modules.js'
+import { identical } from './rebase.js'
+import { changerOf, graphOf, locate, replay, stack, tree } from './stack.js'
+import { order } from './steps.js'
+
+export const hash = body => createHash('sha256').update(body).digest('hex').slice(0, 12)
+
+const converged = async (steps, id) => {
+  const { kind, merges, continues, brought, requiredBy, clashes, failures } = await convergence(steps, id)
+  return { kind, merges, continues, brought, requiredBy, reasons: reasonOf({ clashes, failures }) }
+}
+
+export const kinds = async (steps, layers = replay(steps)) => Object.fromEntries(await Promise.all(steps.filter(converges).map(async step => [step.id, (await convergence(steps, step.id, layers)).kind])))
+
+export const entry = async (steps, address) => {
+  const { id, through } = locate(steps, address)
+  const step = steps.find(step => step.id === id)
+  const layered = stack(steps, id, through)
+  const { files, owners, patchers, overrides } = layered
+  const parent = graphOf(steps).parentOf(id, through)
+  const before = parent === null ? {} : stack(steps, parent, through).files
+  return {
+    id,
+    address,
+    parents: step.parents,
+    title: step.title,
+    story: step.story,
+    convergence: converges(step) ? await converged(steps, id) : null,
+    untested: untested(steps, id),
+    folder: `${'../'.repeat(address.split('/').length)}steps/${address}/`,
+    files: Object.keys(files).sort(order).map(path => ({
+      path,
+      owner: owners[path],
+      patchedBy: patchers[path] ?? [],
+      changedBy: changerOf(layered, path),
+      forks: identical(steps, changerOf(layered, path), path),
+      hash: hash(files[path]),
+      overrides: overrides.find(override => override.path === path && override.step === owners[path])?.over ?? null,
+    })),
+    dependencies: dependencies(files),
+    changes: changes(before, files, [...new Set([...Object.keys(before), ...Object.keys(files)])].sort(order)),
+  }
+}
+
+export const index = async (steps, { name, address, editable = false }) => {
+  const { children, joins, timelines, stacks, located, addresses } = tree(steps)
+  const kind = await kinds(steps)
+  const shown = (line, lane) => line.filter((_, depth) => kind[timelines[lane][depth]] !== 'obsolete')
+  return {
+    codecane: 1,
+    version: manifest.version,
+    name,
+    editable,
+    steps: steps.map(({ id, hash, parents, merges, title }) => ({ id, hash, parents, merges, title, children: children(id), joins: joins(id), kind: kind[id] ?? null, untested: untested(steps, id), data: Object.fromEntries(addresses.filter(stacked => located[stacked].id === id).map(stacked => [stacked, address(stacked)])) })),
+    timelines: timelines.map(shown),
+    stacks: stacks.map(shown),
+  }
+}

package/core/diff.js

@@ -0,0 +1,43 @@
+export const split = text => text ? text.split('\n') : []
+
+export const lines = (before, after) => {
+  const [one, other] = [split(before), split(after)]
+  let head = 0
+  let tail = 0
+  while (head < one.length && head < other.length && one[head] === other[head]) head++
+  while (tail < one.length - head && tail < other.length - head && one.at(-1 - tail) === other.at(-1 - tail)) tail++
+  const [a, b] = [one.slice(head, one.length - tail), other.slice(head, other.length - tail)]
+  const keptFrom = Array.from({ length: a.length + 1 }, () => new Uint32Array(b.length + 1))
+  for (let i = a.length - 1; i >= 0; i--) for (let j = b.length - 1; j >= 0; j--) keptFrom[i][j] = a[i] === b[j] ? keptFrom[i + 1][j + 1] + 1 : Math.max(keptFrom[i + 1][j], keptFrom[i][j + 1])
+  const rows = one.slice(0, head).map(line => [' ', line])
+  let i = 0
+  let j = 0
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) {
+      rows.push([' ', a[i++]])
+      j++
+    } else if (i < a.length && (j === b.length || keptFrom[i + 1][j] >= keptFrom[i][j + 1])) rows.push(['-', a[i++]])
+    else rows.push(['+', b[j++]])
+  }
+  return [...rows, ...one.slice(one.length - tail).map(line => [' ', line])]
+}
+
+const text = body => body && !body.includes(0) ? body.toString('utf8') : undefined
+
+export const changes = (before, after, paths) => paths
+  .filter(path => !(path in before && path in after && before[path].equals(after[path])))
+  .map(path => {
+    const state = !(path in before) ? 'added' : !(path in after) ? 'removed' : 'modified'
+    const [was, is] = [text(before[path]), text(after[path])]
+    if ([before[path], after[path]].some(body => body && text(body) === undefined)) return { path, state, binary: true }
+    const rows = lines(was ?? '', is ?? '')
+    return {
+      path,
+      state,
+      before: was ?? '',
+      after: is ?? '',
+      added: rows.filter(([op]) => op === '+').length,
+      removed: rows.filter(([op]) => op === '-').length,
+      lines: rows,
+    }
+  })

package/core/index.js

@@ -0,0 +1,10 @@
+export { build } from './build.js'
+export { check } from './check.js'
+export { convergence, replayed, trial } from './checks.js'
+export { entry, index } from './data.js'
+export { changes, lines } from './diff.js'
+export { applied, format, made, parse, rebased } from './patch.js'
+export { patchCopies, rebaseLater, revise, writes } from './rebase.js'
+export { serve } from './serve.js'
+export { conflictsOf, describe, graphOf, locate, replay, stack, tree } from './stack.js'
+export { persisted, read } from './steps.js'

package/core/modules.js

@@ -0,0 +1,17 @@
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+export const find = (name, from) => {
+  for (let dir = resolve(from); ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'node_modules', name, 'package.json'))) return join(dir, 'node_modules', name)
+    if (dir === dirname(dir)) return undefined
+  }
+}
+
+export const located = (name, from) => {
+  const dir = find(name, from)
+  if (!dir) throw new Error(`codecane: ${name} is not installed in ${from} or any folder above it`)
+  return dir
+}
+
+export const dependencies = files => 'package.json' in files ? Object.keys(JSON.parse(files['package.json']).dependencies ?? {}) : []