@sylad/cadence 0.2.0

package/dist/state.js

@@ -0,0 +1,126 @@
+import { appendFileSync, existsSync, linkSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { gitCommonDir, gitPath } from './git.js';
+/** État local propre au worktree (notes de clôture). */
+export function stateDir(cwd) {
+    const dir = gitPath(cwd, 'cadence');
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** État local commun à tous les worktrees (verrou et journal des livraisons) : une seule livraison par dépôt. */
+export function sharedStateDir(cwd) {
+    const dir = join(gitCommonDir(cwd), 'cadence');
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function readNext(dir) {
+    const file = join(dir, 'next.md');
+    if (!existsSync(file))
+        return null;
+    const [head, ...rest] = readFileSync(file, 'utf8').split('\n');
+    const lines = rest.map((l) => l.replace(/^- /, '')).filter(Boolean);
+    return { date: head.replace(/^# /, '').trim(), lines };
+}
+/** Remplace les notes pour la prochaine session ; sans ligne, les efface. */
+export function writeNext(dir, date, lines) {
+    const file = join(dir, 'next.md');
+    if (lines.length === 0) {
+        rmSync(file, { force: true });
+        return;
+    }
+    writeFileSync(file, `# ${date}\n${lines.map((l) => `- ${l.replace(/\n/g, ' ')}`).join('\n')}\n`);
+}
+export function lockPath(dir) {
+    return join(dir, 'deliver.lock');
+}
+function readLockFile(file) {
+    let text;
+    let ageMs;
+    try {
+        ageMs = Date.now() - statSync(file).mtimeMs;
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const raw = JSON.parse(text);
+        return { pid: Number(raw.pid), sha: String(raw.sha), started: String(raw.started), ageMs };
+    }
+    catch {
+        return { pid: 0, sha: '?', started: '?', unreadable: true, ageMs };
+    }
+}
+export function readLock(dir) {
+    return readLockFile(lockPath(dir));
+}
+/** Verrou tenu : processus vivant, ou fichier illisible mais tout récent (écriture en cours ailleurs). */
+export function lockAlive(lock) {
+    return lock.unreadable ? lock.ageMs < 5_000 : pidAlive(lock.pid);
+}
+/** Pose le verrou de façon atomique (lien vers un fichier complet) ; false s'il existe déjà. */
+export function writeLock(dir, lock) {
+    const tmp = join(dir, `deliver.lock.${lock.pid}.${Date.now()}.tmp`);
+    writeFileSync(tmp, JSON.stringify(lock));
+    try {
+        linkSync(tmp, lockPath(dir));
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+/** Retire un verrou périmé seulement s'il est encore celui qu'on a lu ; sinon le laisse en place. */
+export function removeStaleLock(dir, seen) {
+    const aside = join(dir, `deliver.lock.stale.${process.pid}`);
+    try {
+        renameSync(lockPath(dir), aside);
+    }
+    catch {
+        return false;
+    }
+    const now = readLockFile(aside);
+    if (now && now.pid === seen.pid && now.sha === seen.sha && now.started === seen.started) {
+        rmSync(aside, { force: true });
+        return true;
+    }
+    // Un autre processus a pris le verrou entre-temps : le lui rendre.
+    try {
+        linkSync(aside, lockPath(dir));
+    }
+    catch {
+        // Un troisième l'a déjà repris : le sien fait foi.
+    }
+    rmSync(aside, { force: true });
+    return false;
+}
+/** Retire le verrou s'il appartient à ce processus. */
+export function releaseLock(dir, pid) {
+    const lock = readLock(dir);
+    if (lock && lock.pid === pid)
+        rmSync(lockPath(dir), { force: true });
+}
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+export function appendDelivery(dir, day, sha) {
+    appendFileSync(join(dir, 'deliveries.log'), `${day} ${sha}\n`);
+}
+export function lastDelivery(dir) {
+    const file = join(dir, 'deliveries.log');
+    if (!existsSync(file))
+        return null;
+    const last = readFileSync(file, 'utf8').trim().split('\n').pop();
+    return last?.split(' ')[1] ?? null;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@sylad/cadence",
+  "version": "0.2.0",
+  "description": "A small, repo-native working method: a versioned plan linked to your commits, a changelog with screenshots, session rituals and deliveries proven by their effect.",
+  "license": "MIT",
+  "author": "Sylvain Ladoire",
+  "type": "module",
+  "bin": {
+    "raf": "bin/raf.js",
+    "cadence": "bin/cadence.js"
+  },
+  "files": ["bin", "dist", "skills", "agents", ".claude-plugin", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/skills/deliver/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: deliver
+description: Deliver the pushed HEAD of a repository that uses cadence — wait for its CI run, run the configured deploy commands, then VERIFY THE EFFECT with the configured checks. A delivery is only done when its checks pass. Triggers — "/deliver", "ship it", "deploy", "livre", "mets en prod".
+---
+
+# Deliver — a delivery is proven by its effect
+
+`cadence deliver` reads `cadence.yaml` at the repository root:
+
+```yaml
+deliver:
+  ci: github                 # github | none | { command: "…" }
+  deploy:
+    - ./scripts/deploy.sh "$CADENCE_SHORT"
+  verify:
+    - url: https://app.example.com/api/health
+    - url: https://app.example.com/
+      contains: "${SHORT}"   # the new version is the one being served
+```
+
+## Steps
+
+1. Before anything: tests and build green locally, everything committed **and pushed** — the CI can
+   only build what it has received, and `cadence deliver` refuses a sha that is not on a remote branch.
+2. `cadence deliver --dry-run`: read the resolved commands and checks. If there is no `cadence.yaml`,
+   help write one: ask the human for the deploy command, and propose at least one check that proves
+   the NEW version is live (a version string, a new endpoint), not merely that the site answers.
+3. `cadence deliver`. Exit codes: 0 delivered and verified, 1 a step failed, 2 refused before acting.
+4. On failure: read which step failed and why. Fix the cause, commit, push, deliver again. Never rerun
+   blindly, never skip a check to make it pass.
+5. On success: `raf done <id>` for the lots it lists **whose effect you have seen**; if one of them is
+   `visible`, `cadence news build` and deliver the news too.
+
+## Rules
+
+- Never two deliveries at once: a second one can silently overwrite the first one's deploy. The lock
+  enforces it; do not delete a live lock.
+- A green tool status (CI "success", a deploy tool "synced", a job "completed") is not a proof. Only
+  the checks are.
+- Delivering to production is an outward-facing action: follow the human's standing instructions about
+  confirmation before running step 3.

package/skills/session-close/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: session-close
+description: Close a work session on a repository that uses cadence — plan hygiene (lots in progress, commits without a lot, news entries), repository state (uncommitted, unpushed, delivery running), filtered memory, proposals for new skills or agents without creating them, and three lines for next time. Triggers — "/session-close", "let's stop for today", "on ferme", end of the day.
+---
+
+# Session close — close without memorising everything
+
+## Steps
+
+1. Run `cadence session close` (over several days: `--since "2 days ago"`). Exit code 1 means
+   *not closed*: something below is still open.
+2. **Plan hygiene**, lot by lot:
+   - a `doing` lot with no commit in the period → `raf done <id>` if its tests are green,
+     otherwise `raf note <id> "where it stands, what blocks"`;
+   - a commit without a lot that belongs to one → `raf note <id> "commits: <sha> …"`; nothing if it
+     is genuinely outside the plan (docs, chores);
+   - a finished lot marked `visible` without a news entry → `cadence news new <id>`, written for the
+     user, with a screenshot;
+   - rerun until the check part is clean.
+3. **Memory, filtered** (only if you keep a persistent memory): write down what the repository does
+   NOT already say — a trap and its cause, a decision or correction from the human, a collaboration
+   rule. Test: "do `git log` or the docs already say it?" → then no memory.
+4. **Skills and agents, on threshold, PROPOSED**: a skill when the same chain of commands was done by
+   hand at least twice today; an agent update when an agent got something wrong or its domain moved.
+   List them with the benefit; the human decides. Never create them here.
+5. **Clean state**: everything committed and pushed, no delivery running. If the command still exits 1,
+   say what remains and do NOT say the session is closed.
+6. **Three lines for next time**: `cadence session next "…" "…" "…"` — the next `session-start` shows them.
+
+## Do not
+
+- Write a recap of the day into memory: the plan, `raf now` and `git log` are the record.
+- Close, drop or re-scope a lot the human has not agreed to.

package/skills/session-start/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: session-start
+description: Start a work session on a repository that uses cadence — gather the facts (open lots, work done since last time, drift between plan and history, delivery in progress, notes left at the last close), report them briefly, propose three lots from the plan, then WAIT for the human's priority. Triggers — "/session-start", "let's resume", "where are we?", "on reprend", start of the day.
+---
+
+# Session start — resume without reciting
+
+The repository already carries the state: the plan (`docs/plan/raf.yaml`), the history, the notes left at
+the last close. The only thing missing is the human's priority for today. This skill gathers the facts,
+proposes, and stops.
+
+## Steps
+
+1. Run `cadence session start` (after a weekend: `--since "3 days ago"`). If `cadence` is not on the
+   PATH, use `npx -p @sylad/cadence cadence session start`.
+2. Report **briefly**, in the human's language, in this order — never paste the raw output:
+   - **In progress**: each `doing` lot; for a *silent* one, say whether it looks like a forgotten
+     `raf done` / `raf note` (commits exist, work looks finished) or a real stop.
+   - **Done since**: 3 to 6 lines, grouped by lot, not by commit. Mention commits without a lot.
+   - **Drift**: each `✗` line from the check, with the one command that fixes it.
+   - **Delivery in progress** or a stale lock: no new delivery until it is resolved.
+   - **Notes from the last close**, if any.
+3. **The plan drives the work.** Propose exactly three items, each with its id and one sentence of
+   justification, in the order the command gives them: finish what is in progress, then ready quick
+   wins, then the next ready lots. An idea that is not in the plan is only proposed together with the
+   `raf add "…"` that would put it there.
+4. **Stop and wait** for the priority. Start nothing and commit nothing before the answer — the only
+   exception is a `raf note <id> "…"` on a silent lot whose cause is already known.
+
+## After the answer
+
+`raf start <id>` on the chosen lot, then the project's usual development workflow. Every commit cites
+the lot id (`feat(L3): …`) so that the history links itself to the plan.
+
+## Do not
+
+- Decide for the human: close a lot, drop one, create an agent or a skill.
+- Re-read the whole plan or recite project instructions: they are already loaded.