@nynb/sandpaper 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to Sandpaper are recorded here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
+[Semantic Versioning](https://semver.org/).
+
+Each entry is drafted from `brain/log.html` — the same record the agent keeps of its
+own work — via `/sandpaper:release`, never written from scratch.
+
+## [Unreleased]
+
+## [0.2.0] — 2026-07-03
+
+### Added
+- `/sandpaper:release` — draft release notes and a semver bump from
+  `brain/log.html`, then `npm version` + tag + push.
+- `bin/verify-publish.js` (`npm run verify-publish`) — tarball-safety gate:
+  no `site/`, no secrets, size envelope.
+- `.github/workflows/ci.yml` — tests + verify-publish on every push/PR,
+  Node 18/20/22.
+- `.github/workflows/release.yml` — a pushed tag runs tests → verify-publish
+  → `npm publish --provenance` → a GitHub Release.
+- `.github/dependabot.yml` — weekly Actions + npm dependency checks.
+
+## [0.1.0] — 2026-07-03
+
+Initial public release.
+
+### Added
+- The living brain: cover, three lenses (product/engineering/project), three books
+  (log/decisions/learnings), a canvas for elevated explanations.
+- The refine-in-place toolbar (Sand / Hands / Sling) for local editing.
+- `sandpaper install-skill` / `init` / `upgrade` / `rebuild` / `doctor` / `open` — the
+  zero-AI CLI plumbing.
+- 12 `/sandpaper:*` slash commands — the Claude Code-side intelligence.
+- Auto-updating hooks (SessionStart digest injection, Stop stamp-check).
+- The out-link resolver — `brain/` is always publishable, detached or not.
+- The cyanotype "as-built" identity, shared by the brain and the landing page.
+- Published to npm as `@nynb/sandpaper` (`sandpaper` was taken; `sand-paper`
+  blocked by npm's anti-squatting policy — see `brain/decisions.html#d-npm-scope`).
+
+[Unreleased]: https://github.com/codevalley/sandpaper/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/codevalley/sandpaper/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/codevalley/sandpaper/releases/tag/v0.1.0

package/README.md

@@ -14,8 +14,8 @@ readable by you.
 ## Quick start
 
 ```bash
-# in your repo (npm package coming — GitHub install for now):
-npx github:codevalley/sandpaper install-skill
+# in your repo:
+npx @nynb/sandpaper install-skill
 ```
 
 Then, inside Claude Code:
@@ -27,10 +27,10 @@ Then, inside Claude Code:
 And to view it:
 
 ```bash
-npx github:codevalley/sandpaper open      # serves the repo + opens brain/index.html
+npx @nynb/sandpaper open      # serves the repo + opens brain/index.html
 ```
 
-(An npm package is coming as `@nynb/sandpaper`, which will shorten these to `npx @nynb/sandpaper <cmd>`.)
+(Or install straight from GitHub, no npm account needed: `npx github:codevalley/sandpaper install-skill`.)
 
 ## What you get
 
@@ -77,6 +77,7 @@ skips hook wiring and prints the settings snippet instead.
 - `/sandpaper:learn` — record a gotcha or verdict
 - `/sandpaper:canvas` — elevate an explanation into a board on the cover's canvas
 - `/sandpaper:sync` — reconcile the brain against the code; find and flag drift
+- `/sandpaper:release` — cut a release: draft notes from the brain, pick a semver bump, tag, push
 
 **Set up & run**
 
@@ -97,6 +98,29 @@ Two hooks keep the brain current without prodding. `install-skill` wires them in
   nothing changed under `brain/`, it blocks once and asks the agent to stamp.
   Self-limiting: it never loops, and the agent can decline by stopping again.
 
+## Releasing (this repo's own npm package)
+
+Versioning is a Sandpaper feature, not a side process: `/sandpaper:release` reads
+`brain/log.html` since the last tag, proposes a semver bump with reasoning, drafts
+`CHANGELOG.md` from what actually happened (not from scratch), then runs `npm version`
+and `git push --follow-tags`. Pushing the tag hands off to
+[`.github/workflows/release.yml`](.github/workflows/release.yml), which re-runs tests
+and [`verify-publish`](bin/verify-publish.js) (the same tarball-safety checks — no
+`site/`, no secrets, size within envelope), then `npm publish --provenance` and cuts a
+GitHub Release from the changelog section.
+
+CI publishing needs one of:
+- an **`NPM_TOKEN`** repo secret — generate an **Automation** token from your npm
+  account (Access Tokens → Generate New Token → Automation). A regular Publish token
+  won't work if your account requires 2FA for writes — it still demands an interactive
+  OTP, which a CI runner can't provide.
+- or npm **Trusted Publishing** (OIDC) configured for this exact repo + workflow, if
+  your account offers it — no token to store or rotate.
+
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs the same tests + `verify-publish`
+on every push and PR, across Node 18/20/22. [`.github/dependabot.yml`](.github/dependabot.yml)
+keeps pinned Actions (and any future dependency) patched.
+
 ## Publishing the brain
 
 `brain/` is always publishable — point GitHub Pages, Vercel, Netlify, or Cloudflare at

package/bin/verify-publish.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// verify-publish.js — the gate before any npm publish (local or CI). Zero deps.
+// Codifies the checks that used to be manual: the tarball ships only the tool
+// (never site/ or brain content), stays within an expected size/file envelope
+// (a silent jump is the first sign of an accidental inclusion), and carries no
+// obvious secrets. Exit 0 = safe to publish; exit 1 = do not publish, read why.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+const FORBIDDEN_PREFIXES = ['site/', 'test/', '.github/', '.sandpaper/', '.vercel/'];
+const MAX_FILES = 45; // today: 30. A jump past this means something new is shipping — look before raising it.
+const MAX_UNPACKED_KB = 400; // today: ~218 KB.
+const SECRET_PATTERNS = [
+  /sk-[A-Za-z0-9]{20,}/, /ghp_[A-Za-z0-9]{20,}/, /AKIA[0-9A-Z]{16}/,
+  /-----BEGIN (RSA|OPENSSH|EC) PRIVATE KEY-----/,
+  /api[_-]?key\s*[:=]\s*['"][A-Za-z0-9]{10,}['"]/i,
+  /password\s*[:=]\s*['"][^'"]{4,}['"]/i,
+];
+
+const bad = (m) => { console.error('  ✗ ' + m); process.exitCode = 1; };
+const ok = (m) => console.log('  ✓ ' + m);
+
+const pack = JSON.parse(execFileSync('npm', ['pack', '--dry-run', '--json'], { encoding: 'utf8' }))[0];
+const files = pack.files.map((f) => f.path);
+
+const forbidden = files.filter((f) => FORBIDDEN_PREFIXES.some((p) => f.startsWith(p)));
+if (forbidden.length) bad(`forbidden paths in the tarball: ${forbidden.join(', ')}`);
+else ok(`no forbidden paths (checked against ${FORBIDDEN_PREFIXES.join(', ')})`);
+
+if (files.length > MAX_FILES) bad(`${files.length} files exceeds the expected envelope (${MAX_FILES}) — new files? review and raise MAX_FILES if intentional`);
+else ok(`${files.length} files (within the ${MAX_FILES}-file envelope)`);
+
+const unpackedKb = Math.round(pack.unpackedSize / 1024);
+if (unpackedKb > MAX_UNPACKED_KB) bad(`${unpackedKb} KB unpacked exceeds the expected envelope (${MAX_UNPACKED_KB} KB)`);
+else ok(`${unpackedKb} KB unpacked (within the ${MAX_UNPACKED_KB} KB envelope)`);
+
+let hits = 0;
+for (const f of files) {
+  let text;
+  try { text = readFileSync(f, 'utf8'); } catch { continue; } // binary or unreadable — skip
+  for (const re of SECRET_PATTERNS) if (re.test(text)) { bad(`possible secret in ${f} (matched ${re})`); hits++; }
+}
+if (!hits) ok('no secret patterns found');
+
+if (process.exitCode) { console.error('\n  ✗ verify-publish failed — do not run npm publish.\n'); }
+else console.log('\n  ✓ safe to publish.\n');

package/package.json

@@ -1,19 +1,42 @@
 {
   "name": "@nynb/sandpaper",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A living project brain + refine-in-place toolbar for Claude Code projects. npx @nynb/sandpaper install-skill / init / doctor / open.",
   "type": "module",
-  "bin": { "sandpaper": "bin/cli.js" },
-  "files": ["bin/", "src/", "public/", "skill/", "brain/assets/", "README.md"],
-  "keywords": ["claude-code", "skill", "project-brain", "living-docs", "documentation", "agent"],
+  "bin": {
+    "sandpaper": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "public/",
+    "skill/",
+    "brain/assets/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "skill",
+    "project-brain",
+    "living-docs",
+    "documentation",
+    "agent"
+  ],
   "author": "Narayan <codevalley@live.com>",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/codevalley/sandpaper.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codevalley/sandpaper.git"
+  },
   "homepage": "https://github.com/codevalley/sandpaper#readme",
   "bugs": "https://github.com/codevalley/sandpaper/issues",
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "start": "node bin/cli.js help",
-    "test": "node test/parse-test.js && node test/markdown-test.js && node test/edit-test.js"
+    "test": "node test/parse-test.js && node test/markdown-test.js && node test/edit-test.js",
+    "verify-publish": "node bin/verify-publish.js"
   }
 }

package/skill/sandpaper/SKILL.md

@@ -105,7 +105,8 @@ you might forget and a system that cannot silently drift.
 ## Commands
 `/help` (this list) · `/init` (harvest → interview → generate a brain) · `/stamp` (the 6-step
 stamp) · `/canvas` (elevate an explanation into a board on the cover) · `/plan` · `/decide` ·
-`/learn` · `/log` · `/sync` (reconcile + heal drift) ·
+`/learn` · `/log` · `/sync` (reconcile + heal drift) · `/release` (draft notes from the brain,
+pick a semver bump, tag, push) ·
 `/open` (serve + open the brain in a browser) · `/serve` (on-page refine toolbar) · `/theme`
 (re-skin from a brand hex). Run `/sandpaper:help` for the full grouped list.
 

package/skill/sandpaper/commands/help.md

@@ -12,6 +12,7 @@ Show the user the Sandpaper command set, grouped like this, then offer to run on
 - `/sandpaper:learn` — record a gotcha or verdict learning
 - `/sandpaper:canvas` — elevate an explanation into a board on the cover's canvas
 - `/sandpaper:sync` — reconcile the brain against the code; find + heal drift
+- `/sandpaper:release` — cut a release: draft notes from the brain, pick a semver bump, tag, push
 
 **Set up & run**
 - `/sandpaper:init` — scaffold a new brain for this repo (harvest → interview → generate)

package/skill/sandpaper/commands/release.md

@@ -0,0 +1,45 @@
+---
+description: Cut a release — draft notes from the brain, pick a semver bump, tag, push
+argument-hint: "[optional: force patch | minor | major]"
+---
+
+Cut a release of this package $ARGUMENTS. The brain already narrates every session — draft
+from it, never from scratch.
+
+1. **RANGE** — find the last release tag (`git describe --tags --abbrev=0`; none = the whole
+   history). Read every `brain/log.html` worklog entry since that tag's date, plus any
+   `brain/decisions.html` entries in range — that's the real source, richer than raw commit
+   messages.
+
+2. **PROPOSE THE BUMP** — read the range for signal, then ask the owner to confirm (AskUserQuestion,
+   never assume silently):
+   - **major** — a breaking change: a removed/renamed CLI flag or command, an incompatible file
+     format change, anything that breaks an existing install.
+   - **minor** — new capability shipped (a new command, a new CLI flag, a new brain feature).
+   - **patch** — fixes, polish, docs, internal-only changes.
+   If `$ARGUMENTS` already names one, propose it pre-selected but still confirm — a human okays
+   every version bump.
+
+3. **DRAFT THE NOTES** — write a `## [X.Y.Z] — YYYY-MM-DD` section for `CHANGELOG.md` in
+   Keep-a-Changelog style (`### Added` / `### Changed` / `### Fixed` / `### Security` as they
+   apply), one line per real change, in plain user-facing language — not log-entry jargon. Fold
+   in anything still under `## [Unreleased]`. Show the draft to the owner before writing it.
+
+4. **WRITE + TAG** — insert the new section into `CHANGELOG.md` above the previous version (keep
+   `[Unreleased]` empty at the top), update the compare-links footer, then:
+   ```
+   npm version <bump> -m "chore(release): v%s"
+   git push --follow-tags
+   ```
+   `npm version` bumps `package.json`, commits, and tags `vX.Y.Z` in one step — don't hand-edit
+   the version number.
+
+5. **STAMP** — run the rest of `/sandpaper:stamp`: a log row for the release, the cover's NOW,
+   the digest, and a plan-board tick if a task tracked this work.
+
+6. **HANDOFF** — tell the owner the pushed tag will trigger `.github/workflows/release.yml`
+   (tests → `verify-publish` → `npm publish --provenance` → a GitHub Release), which needs either
+   an `NPM_TOKEN` repo secret (an npm **Automation** token — required if the account has
+   `auth-and-writes` 2FA, since only Automation tokens skip the interactive OTP prompt) or npm
+   Trusted Publishing configured for this repo + workflow. Never publish to npm directly from
+   here — that's the release workflow's job, and it verifies before it publishes.