@erclx/canon 4.69.0 → 4.71.0

package/src/teach/workspace.ts

@@ -42,9 +42,20 @@ export const TEACH_ASSETS = 'assets'
  * The one stylesheet every lesson in a workspace links. The name is fixed here
  * rather than chosen per lesson, because the second lesson has to reach the
  * file the first one wrote and a name composed twice is a name that can differ.
+ * This file is workspace-owned: `writeStylesheet` writes it once and leaves it
+ * alone, since a lesson adds its own rules here. It imports `TEACH_STYLESHEET_BASE`
+ * for the tokens and components, which is the half a resync may always replace.
  */
 export const TEACH_STYLESHEET = 'course.css'
 
+/**
+ * The seeded half of a workspace's styling, imported by `TEACH_STYLESHEET`.
+ * `writeStylesheet` rewrites this file from the design source on every call,
+ * since nothing workspace-authored lives in it, which is what lets a design
+ * token move without a `--force` flag discarding a workspace's lesson rules.
+ */
+export const TEACH_STYLESHEET_BASE = 'base.css'
+
 /**
  * The mission heading whose list a session reads as exit criteria. The writer,
  * the reader below, and the record validator all match this one spelling, so a
@@ -1001,31 +1012,40 @@ export interface StylesheetWritten {
   readonly slug: string
   /** Relative to the root, so a caller prints a path a reader can open. */
   readonly path: string
-  /** False when the workspace already held one and this call left it alone. */
+  /** Relative to the root, the re-synced seed `path` imports. */
+  readonly basePath: string
+  /** False when the workspace already held `path` and this call left it alone. */
   readonly written: boolean
 }
 
 export type StylesheetOutcome = StylesheetWritten | TeachRefused
 
-const STYLESHEET_BANNER = [
+const STYLESHEET_BASE_BANNER = [
   'Seeded by `canon teach stylesheet` from the design source in',
-  'src/design/tokens.ts. The tokens and the two components below are the',
-  'system this workspace renders in. Add lesson rules under them and read a',
-  'value through its custom property rather than restating the hex, which is',
-  'what let one workspace fork the palette from every other.',
+  'src/design/tokens.ts, and rewritten on every call. The tokens and the two',
+  'components below are the system this workspace renders in. Read a value',
+  'through its custom property rather than restating the hex, which is what',
+  'let one workspace fork the palette from every other. Add lesson rules to',
+  `${TEACH_STYLESHEET} instead, which imports this file and is never rewritten.`,
 ].join('\n   ')
 
+const stylesheetSeed = (): string =>
+  `@import url('./${TEACH_STYLESHEET_BASE}');\n`
+
 /**
- * Writes a workspace's one stylesheet from the design source.
+ * Writes a workspace's stylesheet pair from the design source.
  *
- * Every workspace used to carry a hand-authored copy, which is how the course
- * palette forked once per workspace. The name is fixed at `TEACH_STYLESHEET`
- * and the folder at `TEACH_ASSETS` for the same reason a second lesson has to
- * reach the file the first one wrote, and this is what puts the values in it.
+ * Every workspace used to carry one hand-authored file, which is how the
+ * course palette forked once per workspace. The names are fixed at
+ * `TEACH_STYLESHEET` and `TEACH_STYLESHEET_BASE`, and the folder at
+ * `TEACH_ASSETS`, for the same reason a second lesson has to reach the files
+ * the first one wrote and names composed twice can differ.
  *
- * An existing stylesheet is left alone rather than replaced. A workspace adds
- * lesson rules to this file as it goes, so overwriting would discard them, and
- * `--force` is the caller saying it wants the seed back.
+ * `TEACH_STYLESHEET_BASE` carries the tokens and the components and is
+ * rewritten every call, since nothing workspace-authored lives in it.
+ * `TEACH_STYLESHEET` imports it, carries a workspace's own lesson rules, and
+ * is written once and left alone, since overwriting it would discard them.
+ * `--force` is the caller saying it wants that file's seed back too.
  */
 export async function writeStylesheet(
   root: string,
@@ -1036,22 +1056,39 @@ export async function writeStylesheet(
   if (!found.ok) return found
 
   const workspace = found.workspace
-  const rel = join(workspace.path, TEACH_ASSETS, TEACH_STYLESHEET)
+  const assetsDir = join(workspace.path, TEACH_ASSETS)
+  const baseRel = join(assetsDir, TEACH_STYLESHEET_BASE)
+  const rel = join(assetsDir, TEACH_STYLESHEET)
+  const basePath = join(root, baseRel)
   const path = join(root, rel)
 
-  if (existsSync(path) && !force) {
-    return { ok: true, slug: workspace.slug, path: rel, written: false }
-  }
-
-  await mkdir(join(root, workspace.path, TEACH_ASSETS), { recursive: true })
+  await mkdir(join(root, assetsDir), { recursive: true })
   await writeFile(
-    path,
+    basePath,
     buildDesignCss(undefined, {
-      banner: STYLESHEET_BANNER,
+      banner: STYLESHEET_BASE_BANNER,
       embedFonts: TEACH_FONT_FACES,
       components: TEACH_STYLESHEET_COMPONENTS,
     }),
   )
 
-  return { ok: true, slug: workspace.slug, path: rel, written: true }
+  if (existsSync(path) && !force) {
+    return {
+      ok: true,
+      slug: workspace.slug,
+      path: rel,
+      basePath: baseRel,
+      written: false,
+    }
+  }
+
+  await writeFile(path, stylesheetSeed())
+
+  return {
+    ok: true,
+    slug: workspace.slug,
+    path: rel,
+    basePath: baseRel,
+    written: true,
+  }
 }

package/standards/plan.md

@@ -124,7 +124,7 @@ This contract inverts the one an intake folder keeps, where an empty slot means
 - Write the plan before implementation starts, and treat it as the scope of the run that executes it.
 - Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
 - Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the contract above fixes which line takes it.
-- Move the plan to `.canon/plans/archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it. The archive nests inside `.canon/plans/` rather than sitting beside it as `.claude/plans-archive/`, so an older layout is a flat sibling by that name and a current one is not.
+- Move the plan to `.canon/plans/archive/` when the work it describes ships or is declined. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it. The archive nests inside `.canon/plans/` rather than sitting beside it as `.claude/plans-archive/`, so an older layout is a flat sibling by that name and a current one is not.
 - Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
 
 ## Anti-patterns

package/standards/tasks.md

@@ -31,6 +31,8 @@ Does not govern:
 ├── priority.md           ← hand-maintained execution order
 ├── backlog.md            ← unordered, what is not being scheduled
 ├── session-<slug>.md     ← optional, what a compaction is about to destroy
+├── archive/              ← shipped tasks, moved by canon tasks archive
+├── declined/             ← decided-against tasks, moved by canon tasks decline
 ├── v09.0-sync-paths.md      # canon-allow-reference: illustrates the vXX.Y-slug filename this section defines
 └── v13.0-toolkit-drift.md   # canon-allow-reference: illustrates the vXX.Y-slug filename this section defines
 ```
@@ -207,7 +209,7 @@ Every task names where it came from, through a `Plan:`, `Groundwork:`, `Intake:`
 
 A task with no origin is either lost context or work nobody decided to do. The invariant runs both ways, and the second direction is the one that bites: a groundwork track, an intake folder, or an open issue that no task points at is work already decided and on its way to being forgotten.
 
-An intake folder answers that direction at folder scope rather than item scope, since one dump dispositions many items and most close without ever becoming a task. What names a folder is every item answered and no task citing it, on the board or in the archive. That is a dump nobody acted on. Counting the archive beside the board is what separates it from one already promoted and shipped, and a check reading the board alone calls every finished folder abandoned.
+An intake folder answers that direction at folder scope rather than item scope, since one dump dispositions many items and most close without ever becoming a task. What names a folder is every item answered and no task citing it, on the board or in the archive. That is a dump nobody acted on. Counting the archive and declined folder beside the board is what separates it from one already promoted and settled, and a check reading the board alone calls every finished folder abandoned.
 
 `Plan:`, `Groundwork:`, and `Intake:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.canon/tasks/`, which makes it `../plans/`, `../groundwork/`, and `../intake/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
 
@@ -258,3 +260,15 @@ Archiving a task archives its plan alongside it, when the closing task is that p
 One act rather than two is what makes the pair safe. The merge is the event that settles a plan, and a `post-merge` hook reaching the archive with nobody watching cannot act on a warning, so a second call after it would be a second failure point leaving the task archived and the plan live.
 
 A task with an open outcome stays on the board, and so does its plan. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file. Cutting means striking the outcome's body: `- ~~<outcome>~~ <why>`. `archiveTask` reads a struck body as cut whatever its checkbox holds, so a task carrying only cut outcomes still archives and a mixed task carries both counts on its success record.
+
+## Declining
+
+A task decided against moves to `.canon/tasks/declined/` rather than `.canon/tasks/archive/`. The two folders answer different questions: archive means the work shipped, declined means somebody decided against doing it. Neither reading fits a task that is merely unscheduled, which stays on `backlog.md` rather than moving anywhere, since nobody has decided against it and it may still rise when the board has room.
+
+`canon tasks decline` carries no outcome-state gate. A task can be decided against at any outcome state, open outcomes included, which is what separates its refusal set from archive's: the two never share one, since a shared gate would let one archive a task that cannot yet ship or decline one that already has.
+
+The decision is recorded on the task itself with a `Declined:` line, in the `Plan:`/`Pull request:` family: `Declined: <reason>, <who> on <YYYY-MM-DD>`. It anchors the same way `Pull request:` does, after the last origin line the task carries. The line is free prose after the colon, since it names no file to link.
+
+Declining a task moves its plan alongside it the same way archiving does, when the declining task is that plan's last live citation. A plan several tasks share stays where it is, and a declined task's plan lands in `.canon/plans/archive/` indistinguishable from a shipped one by folder alone. The task file under `.canon/tasks/declined/` is what records which it was.
+
+The move clears whichever of `priority.md` or `backlog.md` holds the task's row, since a decided-against task most often comes off the backlog before anyone plans it, but a row already promoted to the ordering file is cleared the same way archive clears it.

package/tooling/cloudflare/configs/.github/workflows/deploy.yml

@@ -0,0 +1,103 @@
+name: Deploy
+# canon-no-seed: a stack-specific deploy workflow with no root counterpart by design, parameterized per project on sync rather than mirrored from one.
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      # Fill in this project's own build inputs. A single glob covering the
+      # source tree is enough for most projects; widen it to cover every
+      # path the build reads when it draws on content living elsewhere.
+      - 'src/**'
+  workflow_dispatch:
+
+# Fill in a concurrency group name unique to this project. A second push
+# while a deploy is in flight publishes the newer commit rather than racing
+# it, and the running job is left to finish so a half-uploaded site is never
+# what a reader lands on.
+concurrency:
+  group: deploy
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: 📦 Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+          retention-days: 1
+
+  deploy:
+    name: 🚀 Deploy
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for Cloudflare secrets
+        id: secrets-check
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          if [ -z "$CLOUDFLARE_API_TOKEN" ] || [ -z "$CLOUDFLARE_ACCOUNT_ID" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Skip notice
+        if: steps.secrets-check.outputs.skip == 'true'
+        run: echo "::notice::CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID is not set, skipping deploy. Run the deploy-cloudflare skill to finish setup."
+
+      # This job builds nothing and still needs a toolchain. The checkout
+      # below brings bun.lock, wrangler-action reads it, picks bun on the
+      # strength of it, and installs wrangler with that, so a deploy with no
+      # bun on PATH fails before it reaches Cloudflare. Dropping these steps
+      # as dead weight breaks the deploy on every push.
+      - name: Checkout
+        if: steps.secrets-check.outputs.skip == 'false'
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        if: steps.secrets-check.outputs.skip == 'false'
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Download artifact
+        if: steps.secrets-check.outputs.skip == 'false'
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish
+        if: steps.secrets-check.outputs.skip == 'false'
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          # Fill in this project's Pages project name, set when the
+          # deploy-cloudflare skill runs wrangler pages project create.
+          command: pages deploy dist --project-name=REPLACE_WITH_PROJECT_NAME --branch=${{ github.ref_name }}

package/tooling/cloudflare/manifest.toml

@@ -0,0 +1,5 @@
+[stack]
+name = "cloudflare"
+extends = ""
+runtime = "bun"
+scaffold = ""

package/tooling/cloudflare/reference.md

@@ -0,0 +1,24 @@
+# Tooling cloudflare reference
+
+## Overview
+
+The cloudflare stack ships one parameterized GitHub Actions workflow that deploys a static build to Cloudflare Pages. It is keyed on host rather than on framework and carries no dependencies, seeds, or scripts of its own, so it syncs onto a project already carrying `astro`, `vite-react`, or any other stack at the same root without colliding.
+
+## Deploy workflow
+
+- Separate `build` and `deploy` jobs, connected by an uploaded artifact, converged on the shape already running in the closest prior art rather than invented fresh.
+- The deploy job checks for `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` before doing anything else, and skips with a `::notice::` rather than failing when either is absent. A first merge lands ahead of the Pages project existing, and this guard is what keeps that push green.
+- `--branch=${{ github.ref_name }}` on every deploy, which gives every branch a Cloudflare preview URL rather than only `main`.
+- The deploy job checks out the repository and installs Bun even though it builds nothing. `wrangler-action` resolves its package manager from `bun.lock` in the checkout, and dropping that step breaks the deploy on every push once the toolchain it relies on silently goes missing.
+
+## Parameters a project fills in by hand
+
+Three values in the seeded file have no generic default and are set once, right after sync:
+
+- The `paths:` filter under the `push` trigger. The shipped default is a single `src/**` glob. Widen it to cover every path the build reads when the build draws on catalogs or generated content living outside `src/`.
+- The `concurrency.group` name. The shipped default is the bare string `deploy`, which is enough for a single-deploy project. Give it a project-specific name only if the project runs more than one deploy workflow.
+- The `--project-name` flag on the `wrangler pages deploy` command. Set it to the name the `deploy-cloudflare` skill creates the Pages project under.
+
+## Re-sync
+
+`configs/` is golden and always overwrites. Re-running `canon tooling sync cloudflare . --write` after hand-editing any of the three parameters above discards that edit and restores the shipped defaults. Re-fill the parameters after any re-sync rather than expecting the file to preserve them.