@the-smithy/create-hearth-site 0.26.0 → 0.27.0

package/README.md

@@ -40,7 +40,8 @@ cd acme-website
 
 Add an API key to `.env.local` (Hearth → the site → API & webhooks → API keys), and run `pnpm dev`. The
 new site's README walks through the first run, previews and troubleshooting. Its `HOSTING.md` covers deploying to
-Netlify or Vercel, and its `AGENTS.md` holds the instructions for coding agents.
+Netlify or Vercel, and its `AGENTS.md` holds the instructions for coding agents, who are set up to find code with
+[Drift](https://github.com/The-Smithy/drift).
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/create-hearth-site",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Start a new client website powered by Hearth: pnpm create @the-smithy/hearth-site",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -30,7 +30,7 @@
   ],
   "devDependencies": {
     "vitest": "^5.0.3",
-    "@the-smithy/hearth-schema": "^0.26.0"
+    "@the-smithy/hearth-schema": "^0.27.0"
   },
   "scripts": {
     "test": "node --test \"test/**/*.test.js\" && vitest run test/blocks.test.ts test/overrides.test.ts"

package/template/AGENTS.md

@@ -4,6 +4,26 @@ This is a client website whose content comes from Hearth, The Smithy's headless
 replaced by `pnpm hearth:update`: notes about this particular site go in `SITE.md`, which you should read too.
 `CLAUDE.md` and `GEMINI.md` only point here, for the assistants that look for those names.
 
+<!-- drift:start -->
+## Finding code: use Drift first
+
+Before grepping or reading whole files, use [Drift](https://github.com/The-Smithy/drift). It costs far fewer tokens.
+
+- `drift query <symbol>` or `drift find <words>`: where something is defined
+- `drift show <symbol>` or `drift sig <symbol>`: its source, or just its signature
+- `drift outline <file>`: a file's definitions and imports
+- `drift refs <symbol>`, `drift importers <file>`, `drift tests --for <file>`: what uses it
+- `drift context <symbol or file>`: all of the above before changing something
+- `drift map`: orientation in a new repo
+
+Never read `.drift-index.json`. Grep is still right for strings and comments. If `drift` isn't installed: `cargo install --git https://github.com/The-Smithy/drift`.
+<!-- drift:end -->
+
+Here, `pnpm hearth:drift` is the way to install or update Drift and its skill: it gets the latest release from GitHub,
+without Rust or an API key, and `pnpm hearth:docs` runs it too. Drift is only for working on the code. The build and
+deploy don't use it, so don't add it to `package.json` or the host's build, and if it can't be installed here, carry on
+with grep.
+
 ## How this site is built: Hearth's code, the site's styling
 
 Everything that works with Hearth is already here, and it's the same in every site Hearth runs: every block type,
@@ -139,8 +159,8 @@ Do these before writing code, and tell the developer what you found:
    fix `.env.local`; don't guess values.
 2. **Get the full reference:** `pnpm hearth:docs` saves Hearth's API guide (every block and its fields, events,
    forms, previews, SEO) to `hearth-api.md`. Read the parts you need from it, and from
-   `node_modules/@the-smithy/hearth/llms.md` for the SDK. It also installs any skills Hearth offers this site (see
-   "Skills" below), so run it again when they're missing. These aren't committed, so some assistants' search skips
+   `node_modules/@the-smithy/hearth/llms.md` for the SDK. It also installs Drift and any skills Hearth offers this site
+   (see "Skills" below), so run it again when they're missing. These aren't committed, so some assistants' search skips
    them: open them by their exact path, or from the terminal if your tool won't.
 3. **"Nothing is published"** means every page is a 404 until editors publish in Hearth. That's not a code
    problem: say so, and don't add placeholder content to work around it.
@@ -153,7 +173,7 @@ and, as the same copies, in `.claude/skills/`, since Claude Code only reads that
 for and when to use it. If your assistant doesn't load them by itself, read the ones that fit the task and follow them.
 Use them for that work, design work in particular, rather than starting from scratch. They aren't committed (a
 `.gitignore` in each folder lists them), so a fresh checkout gets them by running `pnpm hearth:docs`; never edit them,
-because the next run replaces them.
+because the next run replaces them. The `drift` skill works the same way, from `pnpm hearth:drift`.
 
 ## Hosting
 

package/template/README.md

@@ -42,12 +42,17 @@ without touching your styling. See "Styling the site" below.
 ## Working with an AI coding assistant
 
 The project comes with instructions for coding agents in `AGENTS.md`, which Codex, Cursor, Copilot and others read on
-their own. `CLAUDE.md` and `GEMINI.md` point Claude Code and Gemini CLI to it. Once your API key is in `.env.local`:
+their own. `CLAUDE.md` and `GEMINI.md` point Claude Code and Gemini CLI to it.
+
+Agents also use [Drift](https://github.com/The-Smithy/drift) to find code with far fewer tokens. `pnpm hearth:drift`
+installs or updates it and its skill from the latest release on GitHub. The site builds and deploys without it.
+
+Once your API key is in `.env.local`:
 
 1. **Check the connection yourself, or have the agent do it:** `pnpm hearth:check` confirms the key works and
    lists the published pages and the block types they use. It never prints the key.
 2. **Give the agent the full reference:** `pnpm hearth:docs` saves Hearth's API guide to `hearth-api.md` (not
-   committed), and installs any coding-assistant skills Hearth offers your site in `.agents/skills/` and
+   committed), and installs Drift and any coding-assistant skills Hearth offers your site in `.agents/skills/` and
    `.claude/skills/`. The agent's instructions already point it at both.
 3. **Then tell it what to build.** Prompts that work well:
 

package/template/_gitignore

@@ -13,3 +13,6 @@ next-env.d.ts
 
 # Hearth's API guide, downloaded by pnpm hearth:docs for AI assistants.
 hearth-api.md
+
+# Drift's code index, rebuilt as needed.
+.drift-index.json

package/template/package.json

@@ -10,6 +10,7 @@
     "typecheck": "tsc --noEmit",
     "hearth:check": "node scripts/hearth.mjs check",
     "hearth:docs": "node scripts/hearth.mjs docs",
+    "hearth:drift": "node scripts/hearth.mjs drift",
     "hearth:update": "node scripts/hearth.mjs update"
   },
   "dependencies": {

package/template/scripts/hearth.mjs

@@ -2,13 +2,16 @@
 //   pnpm hearth:check   says whether The Smithy has released anything newer than this site uses, checks .env.local and
 //                       the connection to Hearth, then lists what's published
 //   pnpm hearth:docs    saves Hearth's full API guide to hearth-api.md (not committed) for an AI assistant to read,
-//                       and installs any coding-assistant skills Hearth offers this site
+//                       and installs any coding-assistant skills Hearth offers this site, and Drift
+//   pnpm hearth:drift   installs or updates Drift, which finds code for coding agents, from its latest GitHub release
 //   pnpm hearth:update  updates Hearth's code in this site (src/hearth and the other files its manifest lists) to the
 //                       latest release, and the packages it needs; src/theme and your own files stay as they are
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
-import { gunzipSync } from "node:zlib";
+import { gunzipSync, inflateRawSync } from "node:zlib";
 
 const command = process.argv[2];
 /** Stops with a message. Thrown rather than process.exit(), which can crash Node on Windows mid-request. */
@@ -19,6 +22,13 @@ const fail = (message) => {
 
 const PACKAGE = "@the-smithy/create-hearth-site";
 const SKILL_DIRS = [".agents/skills", ".claude/skills"];
+/** Drift's release archive for each kind of machine it has a binary for. */
+const DRIFT_ARCHIVES = {
+  "win32-x64": "drift-x86_64-pc-windows-msvc.zip",
+  "linux-x64": "drift-x86_64-unknown-linux-musl.tar.gz",
+  "darwin-arm64": "drift-aarch64-apple-darwin.tar.gz",
+  "darwin-x64": "drift-x86_64-apple-darwin.tar.gz",
+};
 const MANIFEST = "src/hearth/manifest.json";
 /** The packages hearth:update raises; it leaves the site's other Smithy packages to it. */
 const UPDATED_TOGETHER = [PACKAGE, "@the-smithy/hearth", "@the-smithy/hearth-schema"];
@@ -149,6 +159,20 @@ async function docs() {
   writeFileSync("hearth-api.md", await res.text());
   console.log("✓ Saved Hearth's full API guide to hearth-api.md (not committed). Point your coding assistant at it.");
   await skills(env);
+  // Hearth's guide and skills are what this command is for, so Drift failing doesn't fail it.
+  await drift().catch((err) => console.log(`! Skipped Drift: ${err.message}`));
+}
+
+/** The skills a folder's .gitignore lists, which are the installed ones; anything else there is the site's own. */
+function listedSkills(dir) {
+  const listFile = path.join(dir, ".gitignore");
+  if (!existsSync(listFile)) return [];
+  return readFileSync(listFile, "utf8").split(/\r?\n/).map((l) => l.replace(/^\/|\/$/g, "")).filter((l) => l && !l.startsWith("#") && l !== ".gitignore" && l !== "drift");
+}
+
+function listSkills(dir, names) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, ".gitignore"), ["# Installed by pnpm hearth:docs and hearth:drift; refreshed each run.", ".gitignore", "/drift/", ...names.map((n) => `/${n}/`)].join("\n") + "\n");
 }
 
 /**
@@ -164,10 +188,7 @@ async function skills(env) {
   const safe = (p) => /^[a-z0-9][a-z0-9-]*$/.test(p);
   const names = offered.map((s) => s.name).filter(safe);
   for (const dir of SKILL_DIRS) {
-    const listFile = path.join(dir, ".gitignore");
-    const before = existsSync(listFile)
-      ? readFileSync(listFile, "utf8").split(/\r?\n/).map((l) => l.replace(/^\/|\/$/g, "")).filter((l) => l && !l.startsWith("#") && l !== ".gitignore")
-      : [];
+    const before = listedSkills(dir);
     for (const name of before) if (safe(name) && !names.includes(name)) rmSync(path.join(dir, name), { recursive: true, force: true });
     for (const skill of offered.filter((s) => safe(s.name))) {
       rmSync(path.join(dir, skill.name), { recursive: true, force: true });
@@ -178,15 +199,74 @@ async function skills(env) {
         writeFileSync(target, file.content);
       }
     }
-    if (names.length || before.length) {
-      mkdirSync(dir, { recursive: true });
-      writeFileSync(listFile, ["# Installed by pnpm hearth:docs from Hearth; refreshed each run.", ".gitignore", ...names.map((n) => `/${n}/`)].join("\n") + "\n");
-    }
+    if (names.length || before.length) listSkills(dir, names);
   }
   if (names.length) console.log(`✓ Installed ${names.length === 1 ? "a skill" : `${names.length} skills`} for your coding assistant in ${SKILL_DIRS.map((d) => `${d}/`).join(" and ")}: ${names.join(", ")}.`);
 }
 
 
+/**
+ * Installs or updates Drift from its latest GitHub release, replacing the copy already on the PATH, then has it write
+ * its own skill, so both stay current without a new Hearth release. Only hearth:drift and hearth:docs run this, never
+ * an install or a build: a host doesn't need Drift, and shouldn't download and run a program on every deploy.
+ */
+async function drift() {
+  const releases = process.env.HEARTH_DRIFT_RELEASES ?? "https://github.com/The-Smithy/drift/releases";
+  const windows = process.platform === "win32";
+  const name = windows ? "drift.exe" : "drift";
+  const found = spawnSync(windows ? "where" : "which", ["drift"], { encoding: "utf8" });
+  const onPath = found.status === 0 ? found.stdout.split(/\r?\n/)[0].trim() : null;
+  const have = onPath && spawnSync(onPath, ["--version"], { encoding: "utf8" }).stdout?.trim().split(" ")[1];
+  const tag = (await fetch(`${releases}/latest`, { redirect: "manual" })).headers.get("location")?.match(/\/tag\/([^/]+)$/)?.[1];
+  if (!tag) fail("GitHub didn't say which release of Drift is the latest.");
+  const latest = tag.replace(/^v/, "");
+  const bin = onPath ?? path.join(windows ? path.join(process.env.LOCALAPPDATA ?? homedir(), "Programs", "drift") : path.join(homedir(), ".local", "bin"), name);
+
+  if (have && !lower(have, latest)) console.log(`✓ Drift ${have} is up to date.`);
+  else {
+    const archive = DRIFT_ARCHIVES[`${process.platform}-${process.arch}`];
+    if (!archive) fail(`Drift has no download for ${process.platform} ${process.arch}. Install it with: cargo install --git https://github.com/The-Smithy/drift`);
+    const download = async (file) => {
+      const res = await fetch(`${releases}/download/${tag}/${file}`);
+      if (!res.ok) fail(`Couldn't download ${file} from Drift's releases (${res.status}).`);
+      return Buffer.from(await res.arrayBuffer());
+    };
+    const [body, sums] = await Promise.all([download(archive), download("SHA256SUMS")]);
+    const sum = sums.toString("utf8").split(/\r?\n/).find((line) => line.endsWith(` ${archive}`))?.split(/\s+/)[0];
+    if (sum !== createHash("sha256").update(body).digest("hex")) fail(`${archive} doesn't match its checksum in Drift's release, so it wasn't installed.`);
+    const binary = (windows ? unzip : untar)(body).get(name);
+    if (!binary) fail(`${archive} has no ${name}.`);
+    mkdirSync(path.dirname(bin), { recursive: true });
+    writeFileSync(`${bin}.new`, binary);
+    chmodSync(`${bin}.new`, 0o755);
+    renameSync(`${bin}.new`, bin);
+    console.log(`✓ ${have ? `Updated Drift from ${have} to` : "Installed Drift"} ${latest} at ${bin}`);
+    if (!onPath) console.log(`  Add ${path.dirname(bin)} to your PATH so you and your coding assistant can run drift.`);
+  }
+
+  // Drift's skill follows its version, so like Hearth's skills it's installed rather than committed.
+  for (const dir of SKILL_DIRS) listSkills(dir, listedSkills(dir));
+  const install = spawnSync(bin, ["install", "."], { encoding: "utf8" });
+  if (install.status !== 0) fail(`Drift couldn't install its skill: ${install.stderr?.trim() || install.error?.message}`);
+  console.log(`✓ Installed Drift's skill in ${SKILL_DIRS.map((d) => `${d}/`).join(" and ")}.`);
+}
+
+/** The files in a zip archive, by name. */
+function unzip(zip) {
+  const files = new Map();
+  const end = zip.lastIndexOf(Buffer.from("PK\x05\x06", "latin1"));
+  let at = zip.readUInt32LE(end + 16);
+  for (let i = 0; i < zip.readUInt16LE(end + 10); i++) {
+    const nameLength = zip.readUInt16LE(at + 28);
+    const header = zip.readUInt32LE(at + 42);
+    const start = header + 30 + zip.readUInt16LE(header + 26) + zip.readUInt16LE(header + 28);
+    const body = zip.subarray(start, start + zip.readUInt32LE(at + 20));
+    files.set(zip.toString("utf8", at + 46, at + 46 + nameLength), zip.readUInt16LE(at + 10) === 8 ? inflateRawSync(body) : body);
+    at += 46 + nameLength + zip.readUInt16LE(at + 30) + zip.readUInt16LE(at + 32);
+  }
+  return files;
+}
+
 /** The files in an npm package tarball (.tgz), by their path inside it ("package/…"). */
 function untar(tgz) {
   const tar = gunzipSync(tgz);
@@ -323,7 +403,8 @@ try {
   if (command === "check") await check();
   else if (command === "docs") await docs();
   else if (command === "update") await update();
-  else fail("Usage: node scripts/hearth.mjs check | docs | update [--version x.y.z] [--force]");
+  else if (command === "drift") await drift().catch((err) => fail(err instanceof Stop ? err.message : `Couldn't install Drift: ${err.message}`));
+  else fail("Usage: node scripts/hearth.mjs check | docs | drift | update [--version x.y.z] [--force]");
 } catch (err) {
   if (!(err instanceof Stop)) throw err;
   console.error(`\n✗ ${err.message}\n`);